REST API Endpoints

First make sure you've created at least one REST API Service in your app. After you've created a REST API Service, you'll be prompted to add new Endpoints for your service.

An Endpoint is a specific path associated with your API service that is appended to the Dev URL or Prod URL. These are used to make HTTP requests from your application to your API using standard GET, POST, PUT, PATCH, and DELETE methods.

Endpoints are usually associated with a particular resource. For example, if your app is about cooking you might have a group of Endpoints for a 'recipes' resource so that users can perform CRUD operations (create, read, update, and delete) on recipes. And maybe another group of Endpoints for an 'articles' resource.

These Endpoints can then be used by a Fetch component or API Request Action in your app to work with your data.

Adding an Endpoint

To add an endpoint, simply click the Add New Endpoint button from one of your configured REST API Services.

Configuring an Endpoint

Creating a new Endpoint requires several configuration steps that you'll be guided through. Depending on the type of Endpoint you are creating, some settings may not be available and others may be optional.

Basics

Property	Description
Name	Add a name to the Endpoint to identify it in the Draftbit builder interface.
Method	Select an HTTP method to make the appropriate request depending on your API endpoint. Available HTTP methods: - GET (Read) - POST (Create) - PUT (Update) - PATCH (Update) - DELETE (Delete)

Object & Role

We utilize objects and roles in our queries to optimize fetching and caching data in your app. They also help keep the UI updated when data changes somewhere in your app. You should only have one Object and Role combination (i.e. Get Many Posts) per API service.

Property Description

Role Roles describe what this Endpoint intends to do, i.e. the verb (e.g. Get Many). You can select an option from the dropdown.

For example, if you're creating an Endpoint that returns an array of many blog posts, you would select Get Many

Available roles:
- Get One (get a single record)
- Get Many (get multiple records)
- Create (create a new record)
- Update (update an existing record)
- Delete (delete an existing record)
- Login (authenticating a user)
- Register (registering a user)
- Me (get the current user)
- Refresh Token (handling a refresh token)

Object Object describes what data type the Endpoint manipulates and are typically described with nouns (i.e. Post). You can type a new value into the input or select an existing Object type from the dropdown.

For example, when you are building a blogging app, the Endpoints for fetching a list of posts and creating a new post should both have the same Object type, such as Post.

Property	Description
Role	Roles describe what this Endpoint intends to do, i.e. the verb (e.g. Get Many). You can select an option from the dropdown. For example, if you're creating an Endpoint that returns an array of many blog posts, you would select `Get Many` Available roles: - Get One (get a single record) - Get Many (get multiple records) - Create (create a new record) - Update (update an existing record) - Delete (delete an existing record) - Login (authenticating a user) - Register (registering a user) - Me (get the current user) - Refresh Token (handling a refresh token)
Object	Object describes what data type the Endpoint manipulates and are typically described with nouns (i.e. Post). You can type a new value into the input or select an existing Object type from the dropdown. For example, when you are building a blogging app, the Endpoints for fetching a list of posts and creating a new post should both have the same Object type, such as `Post`.

Path & Parameters

The Path will be appended to the base URL you defined when creating the associated REST API Service.

In this example, https://api.example.com is the base url for the API service and /posts/123 is the endpoint path.

If we had a connection to the above example API, our Endpoint path to get a post by a dynamic value like id would look like this: /posts/{{id}}.

The Path also supports any standard query string parameters and these can also be combined with the {{variable}} syntax.

For example, we might have an endpoint for our API that accepts query string parameters to further refine the query, such as:

/posts?author_id={{author_id}}

Or even something more complex, like this:

/posts?where[author_id][eq]={{author_id}}&where[is_published][eq]={{is_published}}

Property	Description
Path	Appended to the Base URL to complete your request. In the case of dynamic values, pass a `{{variable}}`. For example, `/posts/{{id}}` You can pass as many variables as needed in your Path
Path Test Values	Provide test values for each `{{variable}}` defined in the Path that will be used to test the Endpoint before saving. This option is only available for dynamic values and hence requires one or more variables be defined in the Path.

Request Body

Only available for POST, PUT or PATCH requests.

Here you can define a body structure using valid JSON format for the request.

To create a variable for passing data, use {{variable}} syntax as values for the keys defined in the Body Structure. This way, you can map these variables when sending an API request from a Fetch component or API Requst Action.

For example, if we are creating an Endpoint that is making a POST request to our API that stores a new article in our database, we might pass a JSON structure like this as the body of our request:

{
  "title": {{title}},
  "content": {{content}}
}

Of course, you can also pass more complex JSON structures if your apps requires it.

{
  "create": {
    "type": "post",
    "fields": [
      { "key": "title", "value": {{title}} },
      { "key": "content", "value": {{content}} }
    ]
  }
}

Property	Description
Body Structure	The JSON structure of your request body. In the case of dynamic values, pass a `{{variable}}`. For example, `/posts/{{id}}` You can pass as many variables as needed in your Body Structure
Request Body Test Values	Provide test values for each `{{variable}}` defined in the Body Structure that will be used to test the Endpoint before saving. This option is only available for dynamic values and hence requires one or more variables be defined in the Body Structure.

To preview the structure of the request's body, including any test values, you can switch to the Body Preview tab:

Headers

You can set HTTP headers for this specific Endpoint here. If you need to set HTTP headers for ALL Endpoints that will be associated with this Service, you can set them in the Service's configuration. Any header defined by the API service will be automatically added here.

If you have existing headers set on the Service level and create the same headers for an Endpoint, the headers for the Endpoint will be used.

You can type a value directly into the value field or select a variable that you've created from the dropdown.

Property	Description	Example
Key	The HTTP header name	`Authorization`
Value	The value or variable associated with the header	`auth_token (Device Variable)`

📘
Default Values
By default, Draftbit sets the Accept and Content-Type headers to application\json since Draftbit only supports JSON data.

Test & Preview Response

Once you configured your Endpoint, you can then click preview the full Endpoint URL and click the Test button to test the request.

If the request is successful, the response will be displayed. If the server returns a response with an error the status code and message will be displayed.

⚠️
Don't use Skip!
Using Skip will let you use your Endpoint without testing, BUT you will not be shown a list of available fields for data returned by this Endpoint when using it in a Component or Action and you'll lose other benefits from having a data schema associated with your Endpoint.
If for some reason you really need to skip, you should come back and Test as soon as possible.

Editing an Endpoint

Click on one of your existing Endpoints in the API & Cloud Services modal to adjust any of the previously configured settings for your Endpoint.

Duplicating an Endpoint

To duplicate an Endpoint, click the overflow menu (...) for the Endpoint you want to duplicate and then click Duplicate.

Deleting an Endpoint

To delete an Endpoint, click the overflow menu (...) for the Endpoint you want to delete and then click Delete.

❗️
This is permanent
When you delete an Endpoint all Fetch components and API Request Actions that reference the Endpoint will also be reset. This can't be undone!

CORS Issues

If you encounter CORS issues, you can update your server to allow access from the following origins:

Additional Resources

MDN Docs - Request.mode
MDN Docs - Request Credentials
Endpoint – What is an API Endpoint?
Draftbit uses React Query under the hood.

REST API Endpoints

Adding an Endpoint