Betty Blocks REST API
In this article
In this article, you'll learn how to request the Betty Blocks REST API to receive data in JSON formatting.
Robert van Boesschoten
Last updated: 17-10-2019
With the Betty Blocks API, it’s possible to communicate with your application from another Betty Blocks application or an external application. This article will explain the possibilities of the API.
To be able to access the API an authentication needs to be set up. The Betty Blocks API is protected with HTTP basic authentication so without a proper authentication it will not be possible to create a connection.
To set up the authentication, an API user should be created. This can be done by granting an existing user API access or by creating a new user with a random (non-existing) email address to give the API access to. It is important to note that the rights of the user are inherited by the API, meaning that if the user cannot create, update or delete models this will also not be possible for the API. The API access can be given to a user within the user management settings of the app, these can be accessed by going to settings and selecting the user management tab. When on this page, access can be given to a user by clicking on the API button of a user. By doing this an API key will be generated and returned.
Beware! This API key is only shown once! Make sure to make a copy of this key because it is not possible to view it again.
Once the API has been generated, the authentication can be set up with HTTP Basic authentication. The username should be the API user’s email address, and the password should be the generated API key.
Keep in mind that if an API user is removed from the app all API calls authenticated with that user will stop working.
When using the API there are a couple of things that are important to note:
The Betty Blocks API uses different HTTP requests to perform different actions. A different URL is needed for every action. The examples below will explain which URL should be used for which action. The examples will be ordered under the HTTP request that should be used with the action. Each example should be appended after the base URL.
Get all records from a model
Parameters can be added to this action after a question mark in the URL. With these parameters, you can alter the data that will be returned through the API. These are the parameters that can be appended to the get URL:
These parameters can be combined by placing an ampersand (&) between them. This way it’s possible to use multiple parameters in one API call to get exactly the data that is necessary.
Get a specific record from a model
Create a new record in a model
The values of properties can be appended to the URL after a question mark. This should be done in the standard notation. When using multiple values these can be separated with an ampersand. It is possible to create a connection with a connected model by using the id of the existing records to the property that should connect with the model.
The API will return an error if a property has the validate presence setting turned on but it doesn’t get a value. When the object is created successfully the API will return the created object.
When posting a file property file should always be used as value for the record name of the posted property. If this is not the case, the API will respond with a 502 error. If the file is posted correctly then the response of the API will be a temporary URL file. This temporary URL can be used to assign the file to a location within the application. This location can either be within a model or within the public files. The following URL should be used to post a file to the public files location.
This URL accepts 2 properties as a parameter: url and filename. The temporary URL that was given in the previous response should be used as value for the url property. The value of the filename property will set a name for the file. If filename has no value, the name of the uploaded file will be set for the filename property.
When executing an action that requires input variables, these can be appended to the URL after a question mark. For input variables no special notation is necessary. If the triggered action should be executed on a specific record then the id of that record should be passed as an input variable.
If the API returns an empty body then the action is executed successfully.
Update a record
The values of properties can be appended to the URL after a question mark, this should be done in the standard notation. When using multiple values these can be separated with an ampersand. If a property has no value then the old value will not change.
Delete a record
If the object is deleted successfully the API will respond with an empty body.
The API will return a status code with every response, these status codes will indicate what happened during the request. Below are the most common responses of the API.
Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
The request has been fulfilled and resulted in a new resource being created. You will get the created record in return.
204 No content
The request was successfully processed but the response has no value. This is a good response when deleting a record.
400 Bad request
The request cannot be fulfilled due to bad syntax or missing data.
The request cannot be fulfilled due to the lack of, or invalid, authorization.
404 Not found
The requested resource could not be found. It has probably been (re)moved or there is an error in the URL.
502 Bad gateway
The application could not fulfill the request, this is an error in the app most of the time. Errors could appear in the application logs. If not, the issue is probably trying something that the app can’t process. Check the request.
These HTTP status codes are a universal internet standard. For more information about status codes, you can take a look at this website: List of HTTP status codes
In this article