You can connect your Dropsource app to REST APIs to incorporate your own (or third party) backend data. Dropsource uses the OpenAPI (formerly and still commonly known as Swagger) specification to build requests to external data sources. The specification describes the endpoints in an API, including the data types each request accepts as parameters and returns in responses, as well as specifying how requests should be authenticated.

To use an API in Dropsource, you need to import a Swagger specification 2.0 file formatted in JSON. Check out the API Requirements for a rundown of what your API can include.

Tools

Depending on the backend platform you’re using, you may be able to generate the Swagger specification automatically, however in many cases you will need to author it separately. Rather than coding the specification manually, you can use a tool such as the Swagger Editor to start by editing an existing sample file, or Stoplight, in which you can generate the specification by entering sample request and response JSON – see the tutorial on using Stoplight with mock data for an overview of that.

However you author your specification, your Swagger file will typically contain a few common structures:

Metadata and Global Info

The root level of your specification file will contain a few items detailing global information about the API, including the Swagger version (which should be 2.0 for Dropsource), and some text fields indicating general information about the API including its title, version, and some optional items such as a description:

You can include certain pieced of information at the root level of the spec to apply it globally, or within the sections for individual endpoints – this is the case for the MIME types the API consumes and produces (Dropsource only supports JSON data):

Location

The final piece of global information to add to your spec at the root level is the location of the API, specified by its host, base path, and the schemes it supports:

If your API is served directly from the URL indicated as the host, the base path is not necessary.

Paths

Each endpoint in your API can be represented in the spec. To use an API in Dropsource, you only need to include those endpoints you plan to make requests to in your app, so there’s no need to document every available endpoint. Your endpoints should be grouped by path, with subsections for the different methods available on each path (e.g. GET, POST etc). Within each path and operations section, your spec will list the detail of how a request should be structured, outlining the parameters accepted and responses returned.

Your specification should include a paths object at the root level, containing a section for each path you plan to use:

This simplified paths object includes four example paths from a Bubble API. As you can see from the /obj/note/{UniqueID} endpoint, path parameters are indicated in curly braces.

Operations

Inside each path in your spec, you can include each available method (e.g. GET, POST, PUT, PATCH, DELETE). Each method represented in a path is known as an operation.

This example represents an API with both GET and POST endpoints on the same path (one to retrieve notes and one to create them).

Only the operation responses are required inside it, but you will often need to send parameters with your requests as well.

Parameters

Your endpoints might require parameters, for example to specify the information you are requesting, or to send data for storage via your API.

Each operation can include an array of parameters – for each one specify a name, a data type, and where the parameter will be passed (e.g. in the path, the query string, the body, or as form data). You can also use optional data fields to indicate a description, whether or not a parameter is required, a default value, and various other details.

The above excerpt (from the API used in the Photo Saver Bubble API) shows a path parameter which identifies a specific data item to retrieve.

Below is an excerpt from a Backendless API showing a login request with the user’s email and password passed as parameters in the body data:

As you can see above, the data type or structure for a parameter can be defined as a schema – the schema can also reference the specification definitions section (more on that later).

The Google Places API you can see in the Dropsource editor Places example app uses a parameter in a request query string:

Any parameters you define in your specification will be available for binding in your Dropsource app – this allows you to send values to your API, including user input and any other app data values you’re working with:

Responses

Your specification needs to describe the data each operation returns. In the responses section, outline what data will come back with each status code the API uses (at a minimum this should include the successful response structure, but often it will also include error responses, so that clients such as your Dropsource app can detect and respond to API request failures).

Inside each status code, indicate the structures that will be returned. This excerpt describes a response that includes an array of notes for a note-keeping app:

Notice that when the type returned is an array, a type must also be indicated for the items inside the array (in this case an object containing various pieces of info about a single note). Like the parameters, each data item needs a name and type/schema.

Error responses will often include an error message, like this example response from an endpoint that returns a specific note:

Response structures can include a variety of optional fields, and can alternatively be defined in the definitions section (more on that next).

Any responses you define in your specification will be available to display or process in your Dropsource app, including arrays – which you can present to the user in a dynamic Element that will automatically populate the required number of UI items when a response is received from the API:

Definitions

In many cases an API will use common structures in more than one endpoint, for example the note in a note-keeping app, which might be associated with a variety of data values, including the note text, the date it was created, the ID of the user who created it, and so on. By defining a structure in the definitions part of your specification, you can reference it in more than one operation for efficiency (e.g. in an endpoint to retrieve notes and in another to create new notes).

The definitions should be placed at the root level of the specification (the same level as the paths).

This excerpt from the Photo Saver app API describes the structure of a picture item, which includes the image as an encoded string, location the image was taken, the date it was created, and its unique ID:

When you include a schema in the definitions, you can reference it in the parameters or responses for an operation, using the schema name in the structure "$ref": "#/definitions/schema-name" :

Security

If your API uses authentication, you will need to include the details in your specification. You can define security requirements within individual operations, or at the root level of the document to apply them to all operations. Include any authentication methods supported by the API in the securityDefinitions, then apply them by name in the security object (for the whole API or individual routes).

Use the security definitions to indicate the type(s) of authentication – Dropsource supports apiKey, basic, and oauth2 (password flow only, not implicit).

The example above demonstrates applying API Key auth to a whole spec. When using OAuth2, you also need to indicate the flow:

APIs often use API Key auth to provide global access to data, with authentication to restrict access to particular users’ data typically implemented using OAuth2 password (see above) or Basic auth:

Any authentication methods included in your spec will be available to configure in your Dropsource app, for example to send a username and password from input Text Fields, or store an access token value returned from a login request:

For more details on how to specify authentication in your API spec and implement it in your Dropsource app, see the tutorials on Basic, OAuth2, and API Key security.

Using your Specification

The official Swagger/OpenAPI version 2.0 specification and guide outline what your spec can include.

If you haven’t yet set up a backend, you can start from the specification to model the data first – some backend platforms import spec files, and codegen tools can generate the beginnings of your backend code. If you are authoring a spec file manually, it’s worth running it through a validator to troubleshoot any issues prior to importing it into Dropsource (you can paste your JSON into the Swagger editor and it will automatically validate it). If you aren’t yet ready to create your backend API or specification, you can use one of the demo library APIs you’ll see in the Dropsource editor, or try out one from the Dropsource sample specification GitHub repo.

Once you’re ready to connect your API to Dropsource, check out the Connecting to an API documentation and the API tutorials.