API Examples & Usage

Below we show several different ways to access and test your API using CURL and Javascript including getting your token, passing your token and doing basic GET and PUT calls.

User Registration

If you want to create USERS aside from the bootstrapped ADMIN/TEST users, you can register them easily with the following api:

curl -v -H "Content-Type: application/json" -X POST -d '{"username":"fflinstone","password":"yabbadabbadoo","email":"fflintstone@bedrock.com"}' http://localhost:8080/register

Authorization Calls

The beapi-java-demo has built in JWT token authetication so you do not have to worry about auth/validation... you merely USE IT! So before you can call any API, you have to first validate and get a token back; that token is then used for all subsequent calls. Below are example in Curl and Javascript on how to make these calls.

Authorizing Via Curl

The first thing you will need to do before you make any API calls is you will need to AUTHORIZE and get a token that you can then pass to the API's. To do this, you will pass the 'root' login/password that you entered in your '~/.beapi/beapi_api.yml' file when initially doing your setup in the following command:

curl -v -H "Content-Type: application/json" -X POST -d '{"username":"fflintstone","password":"yabbadabbadoo"}' http://localhost:8080/authenticate

...or if you are calling from a remote machine...

curl -H Origin: http://YOUR.IP.ADDRESS -H "Content-Type: application/json"--request POST -d '{"username":"login","password":"password"}' http://localhost:8080/authenticate

If you configured your environment properly, you should get something like this:

{"token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTY2MDA4NzM1OSwiaWF0IjoxNjYwMDY5MzU5fQ.bR8lgrGlzCmHKhXC1D_LF-vVmFINAVX9kgA2n-EiIbslYaix......"}

That weird 'token' value is what you pass to ALL API calls to validate who you are and your security ROLES.

Authorizing Via Javascript

To do the same thing and get your token in Javascript for your frontend, you can do something similar to the following and store it in a token for use on following calls:

$.ajax({
    type: 'POST',
    url: window.url + "/authenticate",
    cache:false,
    async:true,
    contentType: 'application/json',
    data: JSON.stringify(jsonData),
    //dataType:'json',
    headers: {
        'Access-Control-Allow-Origin': '*'
    },
    xhrFields:{
        withCredentials: true
    },
    crossDomain: true,
    success: function (data, textStatus, xhr){
    ...
    },
    complete: function (xhr, textStatus) {
    ...
    }
}).done(function(data, textStatus, jqXHR) {
...
}).fail(function(jqXHR, textStatus, errorThrown) {
...
})

API Call Examples

Getting started with making API calls can be messy, so we provided some basic API calls to provide as templates for you to get started...

Calling API Via Curl

GET Example

curl -H "Content-Type: application/json" -H "Authorization: Bearer {token}"  --request GET "http://localhost:8080/v{appVersion}/user/show/test"

PUT Example

curl -H "Content-Type: application/json" -H "Authorization: Bearer " --request PUT -d "{'title':'testamundo'"} "http://localhost:8080/v1.0/dept/update"

NOTE: Always remember to replace version (here represented by v1.0) with the current version of your application. If you are unsure, check your gradle.properties for 'apiFrameworkVersion'.

Calling API Via Javascript

GET Example

var tmp = JSON.parse(window.token);

const data = null;
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
    if(this.readyState === this.DONE){
        switch(this.status) {
          case 200:
            console.log("SUCCESS : "+this.responseText);
            break;
          case 401:
              console.log("FAIL : "+this.responseText);
            break;
          default:
            alert(this.responseText);
        }
    }
});

xhr.open("GET", "http://localhost:8080/v1.0/hook/getHookServices");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer "+tmp.token);
xhr.send(data);

PUT Example

var tmp = JSON.parse(window.token);

const data = {
    service: service,
    callback: callback,
    authorization: authorization
}

const xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function () {
    if(this.readyState === this.DONE){
        switch(this.status) {
          case 200:
            console.log("SUCCESS : "+this.responseText);
            break;
          case 401:
              console.log("FAIL : "+this.responseText);
            break;
          default:
            alert(this.responseText);
        }
    }
});

xhr.open("PUT", "http://localhost:8080/v1.0/hook/create");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer "+tmp.token);
xhr.send(JSON.stringify(data));

NOTE: Always remember to replace version (here represented by v1.2.x) with the current version of the BeAPI Framework. If you are unsure, check the gradle.propertiesb> for 'apiFrameworkVersion'.

User Management

Once you have most of your application setup, you will want to add/edit users & user roles. This can be done very easily through the API's.

User API's

Create User Example

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request POST -d "{'username': 'guesttest1','password':'testamundo','email':'guest1@guesttest.com'}" "http://localhost:8080/v1.2.0/person/create"

Show User (SuperUser Call Example)

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request GET "http://localhost:8080/v1.2.0/person/show/1"

Show Self Example

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request GET "http://localhost:8080/v1.2.0/person/show

Update User (SuperUser Call Example)

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request POST -d "{'username': 'guesttest1','password':'testamundo','email':'guest1@guesttest.com'}" "http://localhost:8080/v1.2.0/person/update/56"

Update Self Example

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request POST -d "{'username': 'guesttest1','password':'testamundo','email':'guest1@guesttest.com'}" "http://localhost:8080/v1.2.0/person/update"

Delete User (SuperUser Call Example)

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request DELETE "http://localhost:8080/v1.2.0/person/delete/1"

User Role API's

Even though you created a user, they can't access anything until you assign them a 'ROLE' and this ROLE is assigned to an endpoint. Think of a 'ROLE' like a SECURITY GROUP that users belong to that grants them access.

Create User Role Example

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request POST -d "{'personId': '56','roleId':'1'}" "http://localhost:8080/v1.2.0/personRole/create"

Delete User Role Example

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer "  --request DELETE "http://localhost:8080/v1.2.0/personRole/delete/56"

NOTE: While you will normally have to delete dependencies (such as THE USER ROLE) prior to deleting PERSON due to the foreign key dependency, this is taken care of for you in the current implementation. All you have to do is 'delete person' and the related 'person role' record is automatically deleted as well.

Provided Endpoints

The Beapi Starter provides endpoints that are not visible in your project but can be called via API endpoints. These are also secured via IO State files (like all your other endpoints) but generally don't have to be changed. Below we go over each one of these and the endpoints provided...

APIDocs

These are the endpoints for accessing the apidocs. Pretty self explanatory

Endpoint	Request Params	Response Params
/{version}/apidoc/show		*

Authorities/ROLES [ADMIN ONLY]

Since 'authorities' need to be added BUT can be a point of RISK, we maintain strict control of the endpoint in the starter. Below are the endpoints that are provided through the plugin:

Endpoint	Request Params	Response Params
/{version}/authority/create	authority	id, authority
/{version}/authority/list		(List) id, authority

Connector [ADMIN ONLY]

The 'connector' controller provides a way to RELOAD your API RULES without restarting your servers.This allows you to apply changes to an IO State file and load it up to a server to update rules on the server and 'PUSH' all changes to subscribing services.

Endpoint	Request Params	Response Params
/{version}/connector/listFiles		(List) filename
/{version}/connector/update	*special	*special

NOTE: Updating our our API Rules 'on-the-fly' is VERY special (as no other API tool or framework can do this without changing code and restarting the app/server). We do this by changing the RULES in the IO State file we want to make changes to and then RELOADING the file like so:

curl -v -H "Content-Type: application/json" --data-binary @/home/owen/Desktop/User.json -H "Authorization: Bearer your-token-here" --request POST http://localhost:8080/v1.0/connector/update"

Application Properties [ADMIN ONLY]

This provides a way to report the existing application properties/state

Endpoint	Request Params	Response Params
/{version}/properties/getAll		attempts procCores documentationUrl reservedUris publicEndpoint apichainLimit chainingEnabled batchingEnabled encoding iostateDir staticEndpoint serverType supportedFormats throttle webhook security
/{version}/properties/getProperties		attempts procCores documentationUrl reservedUris publicEndpoint apichainLimit chainingEnabled batchingEnabled encoding iostateDir staticEndpoint serverType supportedFormats
/{version}/properties/throttleProps		(Object) throttle
/{version}/properties/webhookProps		(Object) webhook
/{version}/properties/securityProps		(Object) security

Users

These are the endpoints for User management. These are provided for managing all the users in your system.

Endpoint	Request Params	Response Params
/{version}/user/show	permitAll[] ADMIN[id]	permitAll id version username email enabled accountExpired ADMIN id version username email enabled accountExpired firstName lastName
/{version}/user/showById [ADMIN]	id	id version username email enabled accountExpired firstName lastName
/{version}/user/getByUsername	permitAll[] ADMIN[id]	id version username email enabled accountExpired firstName lastName
/{version}/user/update [ADMIN]	permitAll[] ADMIN[id]	id version username email enabled accountExpired firstName lastName passwordExpired accountExpired oauthProvider accountLocked password oauthId avatarUrl
/{version}/user/create	permitAll[] / ADMIN[id]	id version username email enabled accountExpired firstName lastName passwordExpired accountExpired oauthProvider accountLocked password oauthId avatarUrl
/{version}/user/list [ADMIN]		id version username email enabled accountExpired firstName lastName
/{version}/user/delete	id	id

Troubleshooting

Check that the IO State request values for your ROLE, match what you are sending
Check that you are calling the correct endpoint.
Check that you are sending the proper headers and token.
Make sure the version you are using is correct.
9 times out of 10, if you have any kind of error, the thrown stacktrace will tell you precisely what was misconfigured.