Advanced Functionality

Batch Examples Using Curl

Below are example of batch calls taken directly from the integration tests in the framework to give you an example of how to write them:

POST Batch Call EXAMPLE (no concatenation)

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer " --request POST -d "{'batch': [{'name': 'test1'},{'name': 'test2'},{'name': 'test3'},{'name': 'test4'},{'name': 'test5'},{'name': 'test6'}]}" http://localhost:8080/b1.0/test/create

GET Batch Call EXAMPLE (with concatenation)

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer " --request POST -d "{'combine':true,'batch': [{'id': '1'},{'id': '2'},{'id': '3'},{'id': '4'},{'id': '5'},{'id': '6'}]}" http://localhost:8080/b1.0/test/show

DELETE Batch Call EXAMPLE (with concatenation)

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer " --request POST -d "{'combine':true,'batch': [{'id': '1'},{'id': '2'},{'id': '3'},{'id': '4'},{'id': '5'},{'id': '6'}]}" http://localhost:8080/b1.0/test/delete

CSV To JSON Tools

Alot of people in your organization may will be asking for help with CSV to JSON conversion. So here are some links to CSV to JSON tools:

• Online CSV to JSON Converter
• Another Online CSV to JSON Convertor

Enabling Your Endpoint To Be Hookable

Every endpoint in the framework has the ability to be hookable via your IO State files which can be found in your '~/.beapi/.iostate/' directory.

Webhooks are optional and are not turned on by default. You can set this variable PER ENVIRONMENT in your '~/.beapi/beapi_server.yml' file by changing the variable 'webhookActive' in your environment to 'true'. The default is:

webhookActive: false

Simply modify the HOOK section in your IO State file for the endpoint of the controller you want to add a hook to in the iostate file by adding a new role. For example, if I wanted to add a new role to the 'person/create' endpoint which looks like the following:

 ...
"create": {
    "METHOD":"POST",
    "DESCRIPTION":"Create new Person",
    "ROLES":{
    "DEFAULT":["ROLE_ADMIN","ROLE_USER"],
    "BATCH":["ROLE_ADMIN"],
    "HOOK":["ROLE_ADMIN"]
},
    "REQUEST": {
        "permitAll":["username","password","email"]
    },
    "RESPONSE": {
        "permitAll":["id","version"]
    }
}
...

For example... if you wanted to allow USER ROLE to access webhooks for the 'create' api, you simple add the role to HOOK like so:

 ...
"create": {
    "METHOD":"POST",
    "DESCRIPTION":"Create new Person",
    "ROLES":{
    "DEFAULT":["ROLE_ADMIN","ROLE_USER"],
    "BATCH":["ROLE_ADMIN"],
    "HOOK":["ROLE_ADMIN","ROLE_USER"]
},
    "REQUEST": {
        "permitAll":["username","password","email"]
    },
    "RESPONSE": {
        "permitAll":["id","version"]
    }
}
...

Create Your First Webhook

To create your first webhook, setup an URL endpoint on a separate service (like AWS Lambda) that we can forward the data to. Enter the url (or IP) into your CORS 'allowedOrigins' in your ~/.beapi/beapi.yml. This will be defined as your URL in your webhook.

Finally, go into your database for your application and type the following SQL Query:

select id from person where email='[your_email]';
// this is how you get your user id

insert into hook (attempts,date_created,format,last_modified,user_id,is_enabled,url,service) values(0,NOW(),'JSON',NOW(),[your_user_id],true,'[your_url]','[your_service]');

And there you have it! Your first webhook!

What Is API Chaining®?

We have all used encoded GET data when sending form data via a POST request. This is considered common practice. Why? Because GET is idempotent and SAFE. Because it is SAFE (meaning it doesn't change data), it is commonly used with other types of requests as a mixed request. This may not be RESTful but it is considered normal and not unsafe. This is what I like to refer to as a single link chain since it has only one link which is the same as it's destination request.

API chaining extends upon this principle in the fact that you can encode GET data in the URL but pass a POST/PUT/DELETE request (much like post GET with a POST form) to chain the request TO or FROM the request method destination link. This can be used to imply GET requests chained TO a final request link (known as a post- chain) or FROM a request link to other implied GET links (known as a pre-chain).

The reason why this is better than practices like HATEOAS/HAL is that it doesn't rely on the link for the relationship... it relies on a common API Object. By relying on a common API Object to apply rules, endpoints/URI's then only become a reference point for data.

For example, when we make our PUT/POST/DELETE requests we can do :

• a post-chain request: a GET request that return the data, then specifies the key we wish to pass to the next 'link' in the chain which will make a GET request returning data, etc until the final request method is matched. This can be illustrated as follows:

  GET > GET > GET > PUT

  
  
• a pre-chain request: same as a post chain request except the request method is matched in the beginning and then sends and id to the GET methods after it is called. This can be illustrated as follows:

  POST > GET > GET

  
  
• a blank chain request (AKA a 'GET' chain): a blank chain has no additional method; it is merely a series of chained GET requests. Basically this takes the returned data from one GET and you give the KEY to get the data for the next GET request in the chain (just like in other chains).

  GET > GET > GET > GET > GET

  
  

API Chaining® Example

POST Post-Chain Example (minus the data)

The POST post-chain would be encoded as follows:

{
    companyName:'Amazon',
    address:'549 S. Dawson',
    zip:'98108',
    chain:{
        key:dept_id,
        combine:'false',
        type:'postchain',
        order:{dept/show:company_id,company/update:return}
    }
}

And then call via Curl (or via javascript) as follows:

curl -v -H "Content-Type: application/json" -H "Authorization: Bearer [access token]" -X POST -d "{'companyName':'Amazon','address': '549 S. Dawson','zip': '98108','chain':{ 'key':'dept_id','combine':'false','type':'postchain','order':{'dept/show':'company_id','company/update':'return'}}}" "http://localhost:8080/v1.0/person/show/1"

Creating A Chain

Now lets break down how this call work. Normally you could never pass more than one method but you can URL encode GET data with UNSAFE Methods (PUT, POST, DELETE); now by only using one unsafe method for the call and only one unsafe method, we can send AS MANY GETS in the chain as we want!

So the rules of a chain are:

• You can have only one PUT,POST or DELETE endpoint per chain
• You can have unlimited GET endpoints in a chain
• The unsafe method (PUT/POST/DELETE) must begin/end the chain
• Chains MUST be called using 'c' followed by the application 'version' (as found in build.gradle) 'b' plus the application 'version' as found in build.gradle - see Usage

Now lets examine how one of the above chain works:

• http://localhost:8080/c0.1/person/show/1: initial endpoint that retrieves the initial dataset
• key : dept_id: the key to return from the initial dataset to the next iteration in the chain
• combine:false: whether to concatenate all data in the chain for return
• type:postchain: tells us the location of the unsafe method in the chain for processing; 'postchain' tells us it is at the end, 'prechain' tells us it is at the beginning.
• dept/show : company_id: second endpoint iteration; id is the key returned for the next iteration in the chain
• company/update : return: As this is the final iteration (and this is a post chain), we return from the chain here

So given the chain above, we can see that the unsafe method(PUT) is at the end of the chain (section/update). We also KNOW that it is there because it was DECLARED as a 'postchain' (rather than 'prechain')