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:
- 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.
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.
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
- 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
- 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
record[PROPERTYNAME]=VALUEto 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 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.
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 records from a model:
- Get a specific record from a model(selected by ID):
- Filter the return by filter:
- Filter the return by view:
- Filter the return by view and filter:
- Filter the return by view and ids:
- Limit the amount of records in the return
- The default limit is set to 100
- Order the return by property:
- Create a record in a model:
- POST a file (get a url back)
/assets(Use file as the record)
- Triggering an action
/api/models/MODEL-UUID/actions/ACTIONUUID/executeEvery 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
- PUT(update) a record
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.
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!