GuidesAPI ReferenceDiscussions
HomeGuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceDiscussions

API Technical Standards and Formats

Suggest Edits

RESTful Design

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

  • Resource-based - Endpoints are named based on the nouns they pertain to, and do not assume actions into the endpoint.
    • ex. PATCH /loans/:id/los-milestones vs. POST /loans/:id/modify-los-milestone
  • Verb Usage - Endpoints utilize the set of standard REST verbs:
    • GET - Querying, Retrieving info about resource. Should be idempotent.
    • POST - Creation of resource
    • PUT - Fully overwriting upsert of new resource
    • PATCH - Update existing instance of resource
    • DELETE - Remove resource

Endpoint Naming

API Resources are always plural. 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.

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 (no more than 600 API calls per second for a single IP) to control rate of web traffic and prevent DoS attacks.

Additionally, in order to specify which tenant you are accessing, every API request must include the blend-target-instance headers. This will be included with your API credential information, or when you are granted access to a new tenant.

curl -X GET \
https://api.beta.blendlabs.com/documents/{{documentId}} \
-H 'authorization: {{YOUR AUTH TOKEN}}' \
-H 'blend-api-version: 2.0.0' \
-H 'cache-control: no-cache' \
-H 'Content-Type: application/json' \
-H 'blend-target-instance: {{YOUR BLEND DEPLOYMENT}}~{{YOUR SPECIAL ID}}' \

Selecting 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: -H 'blend-api-version: 2.0.0' \

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.

When using functionality in the Experimental version, the Blend API Version Header (Blend-Api-Version) can be set to experimental: -H 'blend-api-version: 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

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 UUID in the following example:

api.blendlabs.com/api/loans/uuid/documents/uuid

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/loans?exported=true

Body

These are parameters that are encoded in the request body. These are only available on PUT, PATCH, POST, and DELETE methods and cannot be used with a GET request. The fields in the body are generally data fields that will be written to the data model.

{
  fullName: 'John Borrower',
  isBorrower: true
}

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 - OK
  • 207 - Bulk Mixed Response
  • 302 - Redirect
  • 400 - Malformed Request(Request must be modified before working)
  • 401 - Authentication failed(Credentials incorrect)
  • 403 - Authorization failed(Credentials correct but user has insufficient permissions/authorization)
  • 404 - Resource not found
  • 422 - Invalid Update(Data model state prevents this request, but its 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.

Pagination (Cursors)

Blend uses cursors for pagination. If its possible for a request to return more than ~10-25 results, the endpoint paginates in the form of cursors.
Currently, all queries are ordered based on timestamp of creation descending.

The format of a cursor is:

  • 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)

${direction}.${timestamp}.${id}

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.

// First Request
response body
{
  documents: [document1, document2],
  nextCursor: Base64(`${n}.{ts2}.{id2}`)
  prevCursor: null
}

// Subsequent requests

query params
{ cursor: nextCursor }

response body
{
  documents: [document3, document4],
  nextCursor: Base64(`${n}.{ts4}.{id4}`)
  prevCursor: Base64(`${p}.{ts3}.{id3}`)
}

The nextCursor is the cursor that you should send to the endpoint 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’.

Updated almost 4 years ago