The Betty Blocks API provides you with an easy way to communicate with your application from another Betty Blocks application or external application. This article is meant to show you the possibilities of the API.
After reading this article, you'll know:
- How you can get your API authentication
- Which requests you can do with the API
- How you can start using the Betty Blocks API
- What HTTP Status Codes are and what they mean
Authentication
The Betty Blocks API is protected with HTTP basic authentication. You will need a username and API key for API access. You can generate an API key for a user in the app in the users overview of your application in My Betty Blocks. To get there quick you can go to Tools → User management in the Builder Bar.
Generating a key
Generate an API key for an existing user in your app by clicking the API button on a user, seen in the animation below.
Beware! An API key can only be seen once! When you click the API
button, an API key will be given to you, so make sure to copy this to your clipboard or any other (temporary) place because you won't be able to view it again.
API User
You can also choose to create an API user. You can add a random (non-existing) email address as a user in your app and generate an API key for that user. This way you're not dependent on the specific, existing user. If you remove the user from your app, all the API calls authenticated with that user's API key will stop working.
Example: api-user@domain.com
Once you've generated an API key, you can authenticate your requests with HTTP Basic authentication, where the username is the API user's email address and the password is the generated API key.
Removing API access
When a user's API access needs to be revoked, just click the API
button again in the User Management overview and the API key will be removed.
Possible data requests
The Betty Blocks API uses HTTP requests to perform CRUD-based actions. CRUD stands for Create, Read, Update and Delete, or for HTTP requests: POST
, GET
, PUT
and DELETE
.
- The HTTP verb POST is used to create new resources. REST does not specify how the data is sent, it posts new records and expect the server to provide the appropriate location URI for the new resource. Your POST can only create 1 record (you will have to send multiple POST requests to create multiple records).
- The HTTP verb GET is used to list or retrieve resources. For collections, the service should return an array of items that are members of the collection. These can be the full details, or just information on where to find the additional data about each resource.
- The HTTP verb DELETE is used to delete resources. If a collection URI is specified, the whole collection should be deleted. If an element URI is specified, just that specific item should be deleted. Recommended is creating a boolean on a model to have active and inactive records instead of deleting them permanently.
- The HTTP verb PUT is used to “replace” (update) the content of an existing object with the provided content. If a collection URI is specified, the entire data should be replaced with the provided one, whereas an element URI(ID) would replace that specific element only.
Using the API
Important notes
- HTTPS is required to use the Betty Blocks API. The API does not work on HTTP.
- The base URL of all your API request will always be
https://YOURAPP.bettyblocks.com/api
Every example given further on is appended on this base URL. - You can find the UUID of a filter/model/property/view by looking at your URL if you click on such an item in your app. A string will be added in your URL, which is the UUID. (For example:
c5ad90ff1564ab78304f1bfc9b89ae2
) - Use
record[PROPERTYNAME]=VALUE
to assign values to properties. - The API actually uses the table names instead of the model names. The default table name is just the model name in plural (mostly just
+s
) but if you've changed the model name, the table name won't change, so it could be different. To see the table name, open the model with Advanced Options turned on. - Postman in desktop application, ideal for testing HTTP requests, thus for testing the Betty Blocks API. We've used Postman to show you how the API works (see screenshots below). We advise you to use Postman to test the API.
Example Requests
Every kind of request is accompanied by an example in Postman. Variables can be added in your URL after an ?
. For example:
https://yourapp.bettyblocks.com/api/users?limit=20
To combine multiple parameters in a request's URL, use &
(ampersand). These are automatically added when the parameters are added by using body variables
Uppercased words in the examples are variables, meaning you should change this to real values according to your specific case.
GET REQUESTS
Get records from a model
https://YOURAPP.bettyblocks.com/api/models/TABLENAME/records
Get a specific record from a model by ID
/models/TABLENAME/records/ID
Filter the return by filter
/models/TABLENAME/records?filter_ids=UUID
Filter the return by view
/models/TABLENAME/records?view_id=UUID
Filter the return by view and filter
/models/TABLENAME/records?view_id=UUID&filter_ids=UUID
Return only the values from properties requested
/models/TABLENAME/records?property_ids[]=UUID
Can be used multiple times, as the []
indicates it accepts an array.
Example: /models/TABLENAM/records?property_ids[]=f696056064c24f4cacf2bc788363b568&property_ids[]=1ccadc86ac9c4fbfbd0762f59fe29716
Use a limit on the records returned
/models/TABLENAME/records?limit=AMOUNT
The default limit is set to 100.
Use an offset on the records returned
/models/TABLENAME/records?offset=AMOUNT
Order the return by property
/models/TABLENAME/records?order=UUID:asc
or
/models/TABLENAME/records?order=UUID:desc
POST REQUESTS
Create a record in a model
/models/TABLENAME/records/new
To add records of a related model, you can add the ID's of the existing records to the body variables. For example when you create a new employee in existing companies:
Property: record[first_name]
>>> value
Property: record[last_name]
>>> value
Relation: record[companies]
>>> ID values (for example: 2,5
= 2 companies with ID 2
and 5
)
Create a public file (asset)
/assets
Use file as the request's payload. If the file is posted correctly, the response of the API will be a temporary asset identifier. Example:
"tmp:1562939263-28885-xxxx/image.jpeg"
This temporary identifier 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.
/file_assets/new
This URL accepts 2 values in the request's payload: url
and filename
. The temporary identifier 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.
PUT REQUESTS
Update a record
/models/TABLENAME/records/ID
Include an ID of a record in the URL to collect a record of the used model.
To add records of a related model, you can add the ID's of the existing records to the body variables. For example when you create a new employee in existing companies:
Property: record[first_name]
>>> value
Property: record[last_name]
>>> value
Relation: record[companies]
>>> ID values (for example: 2,5
= 2 companies with ID 2
and 5
)
DELETE REQUESTS
Delete a record
/models/TABLENAME/records/ID
Include an ID of a record in the URL to collect a record of the used model.
The response will contain a 204 No Content
status, as the requested record is deleted.
Actions
Triggering an action
/api/models/MODEL-UUID/actions/ACTION-UUID/execute
Every action can have a model. You'll need the UUID of that model and the UUID of the action to trigger it using the API.
Note: When you trigger an action via the API, var:record
will not contain a value. If you want to execute the action on a record you'll need to give some input variable (i.e. the id of the record).
Triggering an action with input variables
/api/models/MODEL-UUID/actions/ACTION-UUID/execute?inputvar=value
To include an input variable in your request, append the value behind the ?
(questionmark) in the url, or pass them in the request's body.
Action's response: Background vs. foreground
The response received after requesting an action in your app, depends on wether the action is set to background or foreground processing.
Background: The request triggers an action, which is scheduled for background processing. When the action will be processed, is not yet certain. The application won't wait before sending back a response, so you'll receive an empty body with statuscode 201 Created
.
Foreground: The request triggers an action, which is scheduled for foreground processing. The action will be immediately picked up and the application will wait before sending back a response. This takes longer than with background processing, but does include the used variables and outcome of the action.
The request's body and statuscode depends on the outcome of the action.
HTTP status codes
You will receive HTTP status codes from the API informing you about what happened with your request. Below are the most common responses of the API.
200 OK
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.
201 Created
The request has been fulfilled and resulted in a new resource being created. You will get the created record in the return
204 No content
The request was successfully processed but the response has no value. This is a positive response when deleting a record.
400 Bad request
The request cannot be fulfilled due to bad syntax or missing data.
401 Unauthorized
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 you've made an error in the URL.
502 Bad Gateway
The application could not fulfill your request, this is an error in the app most of the time. You should check the logs in the app for errors. If not, you probably trying something the app can't process. Check your request.
These HTTP status codes are a universal internet standard. If you'd like more info about status codes, you can search the web.
Troubleshooting
If you run into any problems, you've most likely made a minor syntax error somewhere. If not, check out all given examples for an example most like your own case. Make sure you've taken the important notes into consideration.
Still having trouble? We'd like to hear you struggles, so we can make sure you can continue developing and nobody else will encounter the same trouble in the future!
You're always free to start a topic on our Forum or get in touch with us directly via the chat logo at the bottom-right of your screen!