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.

Authorization Calls

BeAPI has built in OAuth 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 -H Origin: http://localhost -H "Content-Type: application/json"--request POST -d '{"username":"login","password":"password"}' http://localhost:8080/api/login

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

curl -H Origin: http://localhost -H "Access-Control-Request-Headers: Origin,X-Requested-With" -H "Content-Type: application/json"--request POST -d '{"username":"login","password":"password"}' http://localhost:8080/api/login

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

{"username":"admin","authorities":["ROLE_ADMIN"],"token_type":"Bearer","access_token":"q3s2ov25h8jll757ff5baqhf8nscbjf9"}

That weird 'access_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 + "/api/login",
    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 "  --request GET "http://localhost:8080/v1.2.X/person/show/1"

PUT Example

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

Calling API Via Javascript

GET Example

$.ajax({
    type: 'GET',
    url: window.url+"/v1.2.0/"+path+"?"+string,
    crossDomain: true,
    cache:false,
    xhrFields: {
        withCredentials: false
    },
    beforeSend: function(request){
        request.setRequestHeader('Authorization','Bearer '+window.token.access_token);
    },
    headers:{
        'Content-Type': contenttype
    },
    dataType: datatype,
    success: function(data) {
        if(data){
        ...
        }
    },
    error: function(jqXHR, textStatus, errorThrown) {
            document.getElementById("output_"+count).innerHTML = jqXHR.status+" : "+jqXHR.statusText;
    },
});

PUT Example

$.ajax({
    type: 'PUT',
    url: window.url+"/v1.2.0/"+path,
    data: JSON.stringify(jsonData),
    crossDomain: true,
    cache:false,
    xhrFields: {
        withCredentials: false
    },
    beforeSend: function(request){
        request.setRequestHeader('Authorization','Bearer '+window.token.access_token);
    },
    headers:{
        'Content-Type': contenttype
    },
    dataType: datatype,
    success: function(data) {
        if(data){
        ...
        }
    },
    error: function(jqXHR, textStatus, errorThrown) {
            document.getElementById("output_"+count).innerHTML = jqXHR.status+" : "+jqXHR.statusText;
    },
});

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"

Troubleshooting