Skip to main content

Welcome to our API!​

This site provides an overview of how things work at nullplatform and gives detailed instructions on how to use our REST API.

Organizations, Accounts, etc.​

These are the entities you'll likely work with when using the API:

+--------------+
| Organization | Example: Crypto Inc. ; One per company.
+--------------+
   |   +---------+
   |___| Account | Example: Crypto Kong ; You can have more than one per organization.
       +---------+
            |   +-----------+
            |___| Namespace | Example: Billing, Checkout, Fraud ; You will have more than one per account.
                +-----------+
                       |   +-------------+
                       |___| Application | Example: Payments API, Shipping API ; You will have many per namespace.
                           +-------------+
                                  |   +-------+
                                  |___| Scope | Examples: Production, Stage, Read, Write, US, Europe ; You will have one ore more per application.
                                      +-------+

Access Tokens​

Almost every API endpoint will require you to send an access token through the use of the "Authorization: Bearer..." HTTP header.

How do I get a token?​

Getting a token is easy and dependent on whether the API calls will be placed by people (humans users) or machines (script/integration/automation users).

  • Human users must use their personal access token to place calls to the API. This token is the same one that the UI uses on every API call on the frontend, and can be retrieved using our Chrome Extension.

  • Machine users must place calls using access tokens obtained from an API key. Please refer to the API keys section to learn how to obtain an API key.

Chrome Extension​

We have developed a browser extension that makes it easier to get your personal access token to place calls to our API.

The extension can be downloaded from https://github.com/nullplatform/chrome-extension.

Siamese cat

Listing entities, filtering and sorting​

Entities can be listed by requesting the entity without an ID, for example: GET /account or GET /application, plase read the following rules and conventions:d

  • Filter by query string. Filters must be passed as a query string like GET /account?filter=value.

  • You can filter by multiple values. We support filtering by multiple-values using comma as a separator like GET /account?name=crypto-kong&status=active

  • Sort is available. To sort use the sort parameter specifying the field and the sort order like this: GET /account?sort=name:desc. Available sorts are asc and desc.

  • Paging works with limit and offset parameters. To navigate trough paginated results you can specify offset and limit parameters.

    • offset represents where the cursor starts in the result set. The default is 0.
    • paging amount of results per page. Default is 50 and cannot exceed 200.

  • Specify the parent entity or you'll be unauthorized. You are authorized only to list things that you have access to, so you have to filter by the parent entity. For example, if you are searching for applications, you have to specify under which namespace_id you'll be running the query like this GET /application?namespace_id=1234

  • It's ok to search within multiple parents. You can specify multiple parents where the search needs to run (up to 10). You must have list permissions on every parent, otherwise you'll be unauthorized.

  • Responses. All entities will have a uniform response for list requests, here's an example:

    GET /application?namespace_id=1234
    {
      paging: {
        offset: 0
        limit: 50
      },
      results: [
        {
          // JSON for the first result
        },
        {
          // JSON for the second result
        },
        ...
      ]
    }

Technical conventions​

Use the right domain​

Note that our API is hosted at https://api.nullplatform.com, we do not use the .io domain for the API.

PUT vs. PATCH​

While in many cases PUT and PATCH are treated as synonyms, use PATCH to update a specific field as there are exceptions.

warning

Using PUT on NRN API fully replaces the NRN content, use PATCH unless you're really sure of what you're doing.

Permissions: users, roles, actions, and grants​

Nullplatform has a powerful permission scheme that allows control access at a very granular level. Please read the following paragraphs to understand how to work with at nullplatform:

API endpoints are actions. In almost every case, API endpoints are associated with one action (the exception can be public endpoints). So to execute a certain endpoint you will need permissions to execute that action. In some cases the endpoint might require to execute other calls to other APIs, thus requiring that you have permissions to execute more actions than the specific one the endpoint is declaring.

In every section of this documentation you will find the action associated with the endpoint you're calling. It will usually have the shape of entity:subaction, for example: organization:write or deploy:create

You need a role to do something. On nullplatform every user has one or more roles (eg: developer, owner, ..). Roles have actions associated to them, so if you give somebody the developer role, that will associate the required actions for that developer to be able to create apps or deploy.

You need to get granted access to resources. It's not the same to be a developer in an experimental application vs. a critical one so the same role can be granted for you in one place of the organization but not in another one. Therefore, the actual permission to do something comes from having a role under a certain resource.

Permissions are extended to child resources. If you're a granted the developer role for the whole account, you don't need to ask for permissions on every namespace because a namespace is a child of the account. Moreover, in this case you're also granted to execute deploys on any application and scope because those are also in the hierarchy where you got the developer role.

Putting it all together

  • Action: something that you can do on nullplatform (eg: deploy:create)
  • Role: links what groups of people do (eg: developer) with the actions needed to perform that role ( eg: organization:read)
  • Resources: a portion of your companies assets to which you will be granted access to (eg: "application 8" or " organization 4")

How do I grant access to a certain resource?​

Check the authentication section where you'll find how to POST new grants.