Overview and Best Practices

API Version 1.0, published 02/25/2022

Oasis guarantees that required fields are always present in the given resource. Oasis guarantees fields with validation will only contain the possible values or formats listed. All other data is shown as it exists in the source system.

Resource availability depends on your application's scopes.

Querying data

A query is a read operation that returns a set of data or results. It can be done using filters as outlined in the following table. Filters specify criteria for the returned data set. A modelName can be nft-collections, nfts, users etc

Query

API

Find all model instances using specified filters.

GET /modelName?filter...

Find instance by ID.

GET /modelName/{id}?filter...

Filters

Oasis supports a specific filter syntax: it's a lot like SQL, but designed
specifically to serialize safely without injection and to be native to
JavaScript.

Oasis supports the following kinds of filters:

  • Fields filter
  • Include filter
  • Limit filter
  • Order filter
  • Skip filter
  • Where filter

The following table describes filter types:

Filter type Type Description
fields Object, Array, or String Specify fields to include in or exclude from the response.
include String, Object, or Array Include results from related models, for relations such as belongsTo and hasMany.
limit Number Limit the number of instances to return.
order String Specify sort order: ascending or descending.
skip (offset) Number Skip the specified number of instances.
where Object Specify search criteria; similar to a WHERE clause in SQL.

Syntax

Oasis supports 2 ways to use filters:

  • easy rest syntax
  • programmable JSON syntax

REST syntax

Specify filters in
the HTTP query string:

/modelName?filter=[filterType1]=val1&filter[filterType2]=val2...

or

/modelName/id?filter=[filterType1]=val1&filter[filterType2]=val2...

The number of filters that you can apply to a single request is limited only by
the maximum URL length, which generally depends on the client used.

🚧

Important

There is no equal sign after ?filter in the query string; for example
https://api.oasis.gd/nfts?filter[where][id]=1

If the filter gets too long, you can encode it. For example:

const filter = {
  include: [
    {
      relation: 'nfts',
      scope: {
        include: [{relation: 'user'}],
      },
    },
  ],
};
encodeURIComponent(JSON.stringify(filter));

the url would be:

/nft-collections?filter=<encodeResult>

📘

Tip

If you are trying query filters with curl, use the -g or --globoff option to use brackets [ and ] in request URLs.

Using "stringified" JSON in REST queries

Instead of the standard REST syntax described above, you can also use
"stringified JSON" in REST queries. To do this, simply use the JSON specified
for the Node.js syntax, as follows:

?filter={ Stringified-JSON }

where Stringified-JSON is the stringified JSON of what the nested object version of the filter would look like. However,
in the JSON all text keys/strings must be enclosed in quotes (").

🚧

Important

When using stringified JSON, you must use an
equal sign after ?filter in the query string.

For example: https://api.oasis.gd/nfts?filter={%22where%22:{%22id%22:2}}

For example: GET /nfts?filter={"where":{"id":1234}}

Limits

Rather than serving every result at once, by default, the Oasis API limits the number of entries in responses to 100 per page. You can change the number of results returned by setting the limit parameter. For instance, GET /nft-collections?filter[limit]=30 returns at most 30 NFT collections