GuidesAPI ReferenceDiscussions
HomeGuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceDiscussions

## RESTful Design

Blend API’s follow RESTful design. Specifically, exhibits the follow characteristics:

  • Resource-based - API routes are named based on the nouns they pertain to, and do not assume actions into the route.

    • ex. PATCH home-lending/applications/id/los-milestones vs. POST home-lending/applications/id/modify-los-milestone

  • Verb Usage - Routes utilize the set of standard REST verbs:

    • **GET** - Querying, Retrieving info about a resource/resources. Should be idempotent.

    • **POST** - Creation of resource.

    • **PUT** - Fully-overwriting upsert of a resource

    • **PATCH** - Update existing instance of a resource

    • **DELETE** - Remove a resource

## Route Naming

API routes always use the plural version of a resource's name. 

For example, "lenders" vs. "lender".

## Authentication

Blend supports and recommends API Secret Tokens for authentication. These are provided in the Authorization header using the following schema: `Bearer {ExampleToken}`.

Additionally, in order to specify which tenant you are accessing, every API request must include the `blend-target-instance` header.

This will be included with your API credential information, or when you are granted access to a new tenant.


Blend also supports basic authentication with our public API, which is a standard protocol that requires a username and password encoded in base64 using the following schema: `Basic base64(username:password)`.
We employ a combination of lockout and rate limiting to prevent malicious activity. If someone attempts to authenticate with your API user credentials with the incorrect password 3 times, we lock the API user from taking further action on the platform. 
We employ IP-level rate limiting in two different dimensions to control the rate of web traffic and prevent DoS attacks:
# For unauthorized IPs, no more than 60 API calls per minute
# For authorized users, no more than 12k API calls per minute
To learn more about Blend's API Security Standards see [Blend's API Authentication and Authorization Details](🔗).
## API Versions
You can select which version of the API you are using by passing the Blend API Version Header (blend-api-version) in the request.
You should **always** specify a version in the request to ensure that the release of new versions of the API will not negatively impact your integration.

Blend defaults the version header to the latest **released** version of the API for convenience while you are building an integration. When a new version is released, this will cause your integration to automatically start using the newest API which may have removed or changed the behavior of some functionality you were relying on.
## The Experimental Version
When using functionality in the Experimental version, the Blend API Version Header (Blend-Api-Version) can be set to `experimental`.

This will make sure that you are always directed to the latest experimental version of the API, regardless of it's version number. This is useful because new functionality may remain in the experimental version beyond a single release cycle while the team works to perfect it. Being able to remain on the experimental version without having to change your version header every release is very convenient in these instances. 
Please read the [API Release Process](🔗) for more information on how we release new versions of the Public API and deprecate older versions.
## Formatting
## Content Type
All API requests and responses use `Content-Type: application/json` unless stated otherwise.
## Parameter Structure
There are 3 types of parameter inputs for an HTTP endpoint.
### URL Parameters
These are parameters that are encoded in the URL. They are required and generally are identifiers used to specify a resource. These are meant as exact match locators since you can only provide one value, such as `ID` in the following example: 
  • `api.blendlabs.com/api/home-lending/applications/id/documents/id`
### Query
These are optional params that are encoded after the end of the request URL. They either operate as filters or provide a default value. They are generally used to filter or specify additional details for query requests, such as `exported=true` in the following example: 
  • `api.blendlabs.com/api/home-lending/applications?exported=true`
### Body
These are parameters that are encoded in the request body. The fields in the body are generally data fields that will be written to the data model.

## Data Types
Blend uses the following standards for data types:
### Dates: ISO Dates
`date: 2018-10-26`
### DateTimestamps: ISO Timestamps
`dateOfBirth: 2018-10-26T21:00:05+00:00`
### String Enums: All capital letters, underscore separated words
`validStrings: ['ALL_VALUES', 'SOME_VALUES', 'NONE_OF_THE_VALUES']`
## Response and Error Codes
These are standard HTTP response codes that Blend makes wide use of.
  • **200** - Success
  • **207** - Mixed Response of successes and errors for bulk routes
  • **302** - Redirect
  • **400** - Malformed Request (Request must be modified by the caller before the API will work)
  • **401** - Authentication failed (Credentials incorrect)
  • **403** - Authorization failed (Credentials correct but user has insufficient permissions)
  • **404** - Resource not found
  • **422** - Invalid Update (Data model state prevents this request, but the request itself is not malformed)
  • **500** - Internal Server Error
## Validation
For requests, Blend follows the [Tolerant Reader pattern](🔗). This means that we allow unknown params in the request query/body and simply ignore any unknown params.
For responses, Blend validates strictly.
## Ordering
Currently, all queries are ordered in descending order based on the creation timestamp of the resource.
## Pagination (Cursors)
Blend uses cursors for pagination. If it is possible for a request to return more than 50 results, the route paginates in the form of cursors.
The format of a cursor is:
*Base64( `${direction}.${timestamp}.${id}`)
**Direction** - Enum ['p', 'n'] This defines whether the cursor points to the page before or after the current page.
**Timestamp** - This defines the timestamp of the first/last element on the current page(depending on direction)
**Id** - This is the id of the first/last element on the current page(depending on direction)
The cursor is ingested as an optional query param in requests. It is base64 encoded, and both prev and next cursors will be returned in response bodies.

The nextCursor is the cursor that you should send to the route to receive the next batch of responses, and the previousCursor is the cursor that you should send to receive the previous batch. 
You will know that you have requested the last available page of results when the API responds with a `nextCursor = ‘0’`.