API

Bobuild lets you expose your data via a REST API. This is a powerful feature in many scenarios:

• you want to make your data available to a third-party website or a mobile app
• you want to build a script that retrieves data from your app and pushes it to a third-party system
• you want to build a script that retrieves data from a third party system and pushes it to your app
• you want to build a script that retrieves data from your app, processes it and uploads it back

With this feature you can actually build your own API without any coding. Just define the endpoints you need, the fields you want to expose and the authentication method you want to have. Bobuild provides you with a powerful way to create as many integrations as you and your users need, even with multiple different views of the same data according to the user roles.

tip

Contact us in order to enable it for your app.

Defining your endpoints

Creating an API for your app is a matter of defining one or more endpoints. An endpoint is just the URL that an external client will call, always beginning with https://YOURDOMAIN/_api followed by an arbitraty path that you can decide. This allows you to design your naming scheme in a very flexible way.

For each endpoint you can choose one of the following behaviors:

Endpoint type	HTTP method	Numeric parameter	Description
List	GET	Optional	Returns a list of records matching a given criteria
Create	POST	Optional	Accept data from the client and create one or more records
Modify	POST	Mandatory	Accept data from the client and modify one record
Delete	DELETE	Mandatory	Delete a record

Endpoints with a numeric parameter will be in the form https://YOURDOMAIN/_api/ENDPOINT/1. The numeric parameter can be used freely in the endpoint filter to define an authorization logic.

Example

Suppose you want to expose a catalog of songs and accept submissions of reviews. You'll create the following endpoints:

URL	HTTP method	Type	Description
https://myapp.bobuild.com/_api/songs	GET	List	Return all songs
https://myapp.bobuild.com/_api/song-review/34	POST	Create	Create a new review for the song with ID 34

List

List endpoints return a JSON object holding a list of records matching a given criteria. They are conceptually very similar to a grid widget because they return tabular data. For a list endpoint you'll need to configure:

• the filter criteria to select the records to return
• the list of the fields to return for each record
• the sorting criteria to use to return the records

Records are returned in pages. This means that if your filter matches more than 100 records, only the first 100 will be returned. However, a total property will be returned signalling that there are more records to retrieve. At that point, the client can just invoke the API endpoint again, passing the ?page=2 parameter and so on until the retrieved items match the total property.

Example

A GET call to https://myapp.bobuild.com/_api/songs will return:

{
    "page": 1,
    "total": 305,
    "items": [
        {
            "id": 1,
            "title": "Song nr. 1",
            "year": 1985
        },
        {
            "id": 2,
            "title": "Song nr. 2",
            "year": 1999
        },
        ...
    ]
}

This will only contain the first 100 items. In order to get the next chunk, the client will have to call https://myapp.bobuild.com/_api/songs?page=2 until the retrieved items match the number in the total property.

Note that your clients can supply custom filter parameters. Such parameters will be applied on top of the filter you defined for the endpoint, so they will only have the effect of further restricting the set of records returned by your endpoint. Examples: https://myapp.bobuild.com/_api/songs?year=1999 to get only the records whose year.

Example

Examples of API calls with custom filters:

• https://myapp.bobuild.com/_api/songs?year=1999 (all songs with year = 1999)
• https://myapp.bobuild.com/_api/songs?year:gt=1998 (all songs with year > 1998)

Create

Create endpoints can create one or multiple records with a single call. You can think of them as the API counterpart of a form widget. Clients are supposed to send a JSON payload representing the fields of the record to be created.

When configuring a Create endpoint you'll define which fields will be accepted from the client, and which ones will be required as mandatory. Remember that IDs are always auto-assigned by Bobuild so clients will not be able to supply the ID of the record to be created.

Example

Here's the payload that a client might want to send with a POST request to https://myapp.bobuild.com/_api/song-review/34:

{
  "rating": 4.5,
  "comment": "Feels good"
}

In order to create multiple records with a single call, an array can be sent instead. Let's see how to create multiple songs with one request. Client will send a POST request to https://myapp.bobuild.com/_api/add-songs with the following payload:

[
  {
    "title": "Song nr. 1",
    "year": 1985
  },
  {
    "title": "Song nr. 2",
    "year": 1999
  }
]

In case the creation is successful, a positive reply will be returned with the ID of the newly created record:

{
  "success": true,
  "object": "song_review",
  "id": 675
}

If you created multiple records, the reply will take this form:

{
  "success": true,
  "object": "song_review",
  "id": [675, 676, 677]
}

If the client provides an invalid payload, an error message will be returned:

{
  "success": false,
  "error": "Invalid data for field: cover"
}

Similarly to a form widget, one or more tasks can be attached to a Create endpoint that will be executed after the record creation.

Modify

Similarly to Create endpoints, Modify endpoints are the API counterpart of a form widget. Their purpose is to modify one single record. Clients are not required to submit the entire record but can provide just the subset of the fields they want to modify.

When configuring a Modify endpoint, you define what fields are allowed to be modified.

Example

Here's the payload that a client might want to send with a POST request to https://myapp.bobuild.com/_api/modify-song/34:

{
  "year": 2001
}

If the modification was successful, a positive response will be returned:

{
  "success": true
}

If the client provides an invalid payload, an error message will be returned:

{
  "success": false,
  "error": "Invalid data for field: year"
}

Similarly to a form widget, one or more tasks can be attached to a Modify endpoint that will be executed after the record update.

Delete

A Delete endpoint simply takes an ID of a record to delete and replies back to the client. You can configure a filter criteria to decide if the record can be deleted or not.

If the deletion was successful, a positive response will be returned:

{
  "success": true
}

Otherwise, an error message will be returned:

{
  "success": false,
  "error": "Record not found"
}

One or more tasks can be attached to a Delete endpoint that will be executed after the record deletion.

If you want to expose an API endpoint that performs multiple deletions at a single time (even across different objects) or you want a more fine-grained control over the execution of the tasks before/after the deletion, it is advisable to use a Modify endpoint instead with one or more delete tasks attached to it instead.

Authentication

At the moment Bobuild supports token-based bearer authentication. This means that you'll get a token to use with your endpoints.

Example

This is how you would call the API with the command-line curl tool but the same applies to any framework or library:

curl --header "Authentication: Bearer 75d4f9ba52bde978a881d67a525c8c3d" https://myapp.bobuild.com/_api/songs

Files and images

While basic types such as text, numbers, booleans are returned as plain JSON values, complex types such as files and images are represented in a special way.

When you're calling a List endpoint to read data from Bobuild, they will be returned as URLs to the actual file:

{
    "page": 1,
    "total": 1,
    "items": [
        {
            "id": 1,
            "title": "Song nr. 1",
            "cover": "https://xxxxxxxxxxxxxxxx/song_1_cover.jpg"
        }
    ]
}

When you're calling a Create or Modify endpoint to send data to Bobuild, you'll need to send your binary data as a base64-encoded string along with the file name:

{
  "title": "Song nr. 1",
  "cover": {
    "data": "<base64-encoded binary data>",
    "name": "song_1_cover.jpg"
  }
}

Client libraries

You don't generally need any special library to access an API created on Bobuild because you'll just need to perform HTTP calls with JSON payload. However, we can provide utility libraries for popular programming languages that wrap these calls and help you handle things like pagination with ease. Contact us!

Feature roadmap

• Automatic generation of API documentation based on OpenAPI format.
• Relase of the client libraries on GitHub.