Data API Reference

BitScoop can be used to interact with APIs directly.

You can easily:

  • Simplify the HTTP calls your applications need to make.
  • Improve the efficiency of your applications by filtering data at the source.
  • Gracefully handle data inconsistencies between, or even within, services.
  • Normalize your API calls across services to a standard data interface.
  • Create relationships between API resources -- even if none are explicitly present.

To get started using these features you can configure a Map with endpoints that can be called directly with the Data API. Each configured endpoint becomes available on the dynamically provisioned Data API for the Map.

The BitScoop Data API sits between your application and an API, receives inbound requests from your servers, and triggers outbound requests to the APIs your applications need. The data returned from each endpoint call will be dependent on the configuration, but the URL, headers, and parameters follow a general format.

Getting Started

Consider a minimalistic Map hooked up to the JSON Placeholder service:

{
  "version": "1.0",
  "url": "https://jsonplaceholder.typicode.com"
}

This Map isn't configured with any endpoints, so the Data API is not provisioned for it. But all we need to do to enable the Data API is add a simple endpoint! Let's go ahead an add an endpoint to interact with the "Posts" resource collection on the API.

{
  "version": "1.0",
  "url": "https://jsonplaceholder.typicode.com",

  "endpoints": {
    "Posts": {
      "route": "/posts",

      "single": {
        "route": "/posts/{{ identifier }}"
      }
    }
  }
}

All we've done here is add a single endpoint named "Posts". We've specified that the outbound route associated with this endpoint should be /posts. Furthermore we've overridden the outbound route if the request inbound to the Data API maps to the Call Instance route with an identifier.

The {{ identifier }} snippet takes advantage of a feature called dynamic evaluation whereby values available in the call's "context" are available for substitution before an outbound call is made.

So if we were to make a request to:

https://data.api.bitscoop.com/[ID]/Posts

Provided that we're using the proper value for the ID, the Data API would map the request to the outbound call:

https://jsonplaceholder.typicode.com/posts

Similarly if we were to make a request to:

https://data.api.bitscoop.com/[ID]/Posts/1

The value of 1 is used as the identifier in the context, the outbound route is dynamically evaluated, and an outbound call is made to:

https://jsonplaceholder.typicode.com/posts/1

This brief introduction only scratches the surface of what's possible using BitScoop and the BitScoop Data API. If you'd like to dive deeper, please feel free to check out our examples and community pages!

Call Collection Route ALL

https://data.api.bitscoop.com/[map_id]/[endpoint_name]

The Call Collection route differs from the Call Instance route based on the lack of an extra path parameter identifier. It is also configured separately in the Map JSON specification (collection versus single). There is no stipulation that the Call Collection route must return a specific data type or dimension.

Path:

Name Description
map_id The ID of the API Map for which to call an endpoint.
endpoint_name The name of the endpoint to call.

Headers:

Name Description
X-Populate A JSON serialized directive indicating which relations should be hydrated. This will override the default specified by the endpoint configuration.

ALL Retrieves data from a configured enpoint.

When a call is made to an endpoint a context is created from the raw parameters using the collection configuration on the endpoint specification as a template.

There are several properties available on the context of the request which can be used to dynamically evaluate outbound values.

Name Location Description
environment API Key environment settings. A set of key/value pairs defined on the API Key used to authenticate/authorize a request to the Data API.
parameters Requested URL. The parameters passed into the Data API by way of the query on the original request.
headers Requested URL. The headers passed into the Data API by way of the original request.

Call Instance Route ALL

https://data.api.bitscoop.com/[map_id]/[endpoint_name]/[identifier]

The Call Instance route differs from the Call Collection route based on an extra path parameter identifier. It is also configured separately in the Map JSON specification (single versus collection). There is no stipulation that the Call Instance route must return a specific data type or dimension. In other words, a Call Instance call could return an array. The only limitation would be not being able to use an identifier.

Path:

Name Description
map_id The ID of the API Map for which to call an endpoint.
endpoint_name The name of the endpoint to call.
identifier An identifier that is passed intermediately to the outbound request context.

Headers:

Name Description
X-Populate A JSON serialized directive indicating which relations should be hydrated. This will override the default specified by the endpoint configuration.

ALL Retrieves data from a configured enpoint.

When a call is made to an endpoint a context is created from the raw parameters using the collection configuration on the endpoint specification as a template.

There are several properties available on the context of the request which can be used to dynamically evaluate outbound values.

Name Location Description
environment API Key environment settings. A set of key/value pairs defined on the API Key used to authenticate/authorize a request to the Data API.
parameters Requested URL. The parameters passed into the Data API by way of the query on the original request.
headers Requested URL. The headers passed into the Data API by way of the original request.
identifier Requested URL. The identifier from the inbounded requested URL.