Betty Blocks REST API


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.

 This article will explain:

  1. How you can get your API authentication;
  2. Which requests you can do with the API;
  3. How you can start using the Betty Blocks API;
  4. What HTTP Status Codes are and what they mean.

1. 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 in My Betty Blocks. To get there quick you can go to Settings → Users in your builder bar.

You generate an API key for an existing user in your app by clicking the API button on a user, see the image below.

Beware! An API key can only be seen once! If you click the API button, an API key will be given to you, make sure to copy this to your clipboard or any other (temporary) place because you won't be able to view it again.

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 dependant 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.


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.

Give API acces
You can give a user API access via My BB

2. 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 requets: 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 POSTS 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.

3. Using the API


Important notes

HTTPS
HTTPS is obligated to use the Betty Blocks API. The API does not work on HTTP.
Base URL
The base URL of all your API request will always be https://YOURAPP.bettyblocks.com/api. Every example given futher on is appended on this base URL
UUID's
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)
Assigning properties
Use record[PROPERTYNAME]=VALUE to assign values to properties.
Model name
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. In order to see the table name, open the model with Advanced Options turned on.
Postman
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 followed by an example in Postman. Variables can be added in your URL after an ?.

Uppercased words in the red code texts are variables, meaning you should change this according to your specific case.


GET REQUESTS

Get records from a model:
https://YOURAPP.bettyblocks.com/api/models/MODEL-NAME/records
Get a specific record from a model(selected by ID):
/models/MODEL-NAME/records/ID
Filter the return by filter:
/models/MODEL-NAME/records?filter_ids=UUID
Filter the return by view:
/models/MODEL-NAME/records?view_id=UUID
Filter the return by view and filter:
/models/MODEL-NAME/records?view_id=UUID&filter_id=UUID
Filter the return by view and ids:
/models/MODEL-NAME/records?property_ids[]=UUID's
Limit the amount of records in the return
/models/MODEL-NAME/records?limit=10
The default limit is set to 100
Order the return by property:
/models/MODEL-NAME/records?order=UUID:asc
or /models/MODEL-NAME/records?order=UUID:descGET: Retrieving an array of records
GET request with a filter (city == Alkmaar), ordered by Name and only showing the properties Name and City

POST REQUESTS

Create a record in a model:
/models/MODEL-NAME/records/new
POST a file (get a url back)
/assets (Use file as the record)

POST: Creating a new record
POST request which creates a new record, giving the Name and City properties a value. The response is the newly created record.
Triggering an action
/api/models/MODEL-UUID/actions/ACTIONUUID/execute Every action has a model, you'll need the UUID of that model and the UUID of the action.
Please note that 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/ACTIONUUID/execute?inputvar=value
POST: Triggering an action with input variables
The action triggered creates a new record based upon 2 input variables.

PUT REQUESTS

PUT(update) a record
/models/MODEL-NAME/records/ID
PUT: Update a record
PUT request to update the city-property of the record with id 8


DELETE REQUESTS

Delete a record
/models/MODEL-NAME/records/ID
DELETE: delete a record
Delete request to delete record with id 8. Response is coded 204, No Content.


4. 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 good 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, authorizaiton.
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 fullfill 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.


5. 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 Intercom-logo at the bottom-right of your screen!


Didn’t find what you want?Ask your question on the forum!