API Maps Reference

An API Map is a JSON configuration that controls how the BitScoop platform should interact with a data provider. Maps support endpoints configuration which can be used to dynamically provision a custom Data API.

Authentication & Connections

Many data providers require permission from your end users to read their data. This process is generally handled by a workflow such as OAuth or OpenID and can be handled by the BitScoop API Toolbox with some configuration on the API Map.

You'll need to instantiate Connections to the data provider behind your Map as a place to store authentication and characterizing information about an end user who has giving you permission to read their data. In most cases you'll have one Connection per end user and BitScoop will automatically store the relevant information used to identify this user in the data provider's system.

Collection Route GET POST

https://api.bitscoop.com/maps

The collection route for maps offers methods to interact with every one of your Maps.

GET List all owned API Maps

Returns an array of your Maps.

Name Type Description
id string A UUID4 unique identifier for the Map object.
version string The Map specification version to use (right now only 1.0).
name string An identifying name for the Map.
url string The root URL of the data provider.
parameters object A set of key/value pairs defining HTTP parameters that should be sent with every outbound request.
headers object A set of key/value pairs defining HTTP headers that should be sent with every outbound request.
body object A JSON body that should be sent with every outbound request.
auth object The auth specification.
meta object The meta specification.
endpoints object The endpoint specifications.
models object Model specifications.
created string The date at which the Map was created.
updated string The date at which the Map was last updated.

Example response:

HTTP/1.1 200 OK

[
	{
		"id": "f1fe5cb8cb1043948c90be86d72c8985"
		"version": "1.0",
		"name": "My Map",
		"url": "https://api.example.com",
		"parameters": {
		    "api_key": "1234"
		},
		"headers": {
		    "api_key": "1234"
		}
		"endpoints": {
		    "Stuff": {
		        "route": "/stuff"
		    }
		},
		"created": "2017-05-10T20:24:57.762Z",
		"updated": "2017-05-10T20:24:57.762Z"
	},

	...
]

POST Create a new API Map

Creates a new API Map. The call body should be a JSON document that matches the API Map specification.

Example response:

HTTP/1.1 200 OK

{
    "id": "f1fe5cb8cb1043948c90be86d72c8985"
    "version": "1.0",
    "name": "My Map",
    "url": "https://api.example.com",
    "parameters": {
        "api_key": "1234"
    },
    "headers": {
        "api_key": "1234"
    }
    "endpoints": {
        "Stuff": {
            "route": "/stuff"
        }
    },
    "created": "2017-05-10T20:24:57.762Z",
    "updated": "2017-05-10T20:24:57.762Z"
}

Instance Route GET PUT DELETE

https://api.bitscoop.com/maps/[map_id]

The instance route for Maps offers a methods to interact with Maps on an individual basis.

Path:

Name Description
map_id The ID of the BitScoop API Map.

GET Obtain details about a single API Map

Returns a single Map matching the specified map_id.

Example response:

HTTP/1.1 200 OK

{
    "id": "f1fe5cb8cb1043948c90be86d72c8985"
    "version": "1.0",
    "name": "My Map",
    "url": "https://api.example.com",
    "parameters": {
        "api_key": "1234"
    },
    "headers": {
        "api_key": "1234"
    }
    "endpoints": {
        "Stuff": {
            "route": "/stuff"
        }
    },
    "created": "2017-05-10T20:24:57.762Z",
    "updated": "2017-05-10T20:24:57.762Z"
}

PUT Update details about a single API Map

Updates a single Connection matching the specified map_id.

The posted response body should match the Map specification.

Example response:

HTTP/1.1 200 OK

{
    "id": "f1fe5cb8cb1043948c90be86d72c8985"
    "version": "1.0",
    "name": "My Map",
    "url": "https://api.example.com",
    "parameters": {
        "api_key": "1234"
    },
    "headers": {
        "api_key": "1234"
    }
    "endpoints": {
        "Stuff": {
            "route": "/stuff"
        }
    },
    "created": "2017-05-10T20:24:57.762Z",
    "updated": "2017-05-10T20:24:57.762Z"
}

DELETE Deletes a single API Map

Deletes a single Map matching the specified map_id. This action will not delete associated Connections so as to protect your authorization keys.

Example response:

HTTP/1.1 204 No Content

Connections Route GET POST

https://api.bitscoop.com/maps/[map_id]/connections

Path:

Name Description
map_id The ID of the BitScoop API Map.

GET List all owned Connections

Returns an array of your Connections associated with a specific API Map. The connection object structure contains a few fields that characterize its state and the information associated with it.

Name Type Description
id string A UUID4 unique identifier for the Connection object.
name string The name of the Connection. Not used except for your own organizational purposes.
auth.status.complete boolean A flag indicating whether the third party associated with the Connection has granted the requested scopes.
auth.status.authorized boolean A flag indicating whether the third party associated with the Connection has approved a scope change.
auth.data.access_token string The access token used to sign requests to the external data provider. This token may not be present for all authentication types.
metadata object A free-form object containing the meta data obtained for the Connection using the meta endpoint. This field will not exist if no meta endpoint is configured.
created string The date at which the Connection was created.
updated string The date at which the Connection was last updated.
provider_id string A UUID4 unique identifier of the Map associated with the connection.

Example Response:

HTTP/1.1 200 OK

[
    {
        "id": "f1fe5cb8cb1043948c90be86d72c8985",
        "name": "My Connection",
        "auth": {
            "status": {
                "complete": true ,
                "authorized": true ,
            },
            "data": {
                "access_token": "12345" ,
            }
        },
        "metadata": {
            "id": "123456"
            "email": "john.doe@example.com"
        },
        "created": "",
        "updated": "",
        "provider_id": "09dcac0883a04e45910a32e716ac8ee4"
    },

    ...
]

POST Create a new Connection for the specified API Map

Creates a new connection associated with a specified API Map.

After a Connection is created using the POST method on the collection route, a redirect_url is returned. At this point the connection is incomplete and requires end-user action.

To complete the connection, the returned redirect_url must be visited and permission must be granted to your application. The BitScoop authentication servers will handle the rest of the authentication negotiation for you ultimately redirecting the user who visited the URL.

In development, you can manually visit the redirect_url to complete the connection. If you're integrating BitScoop into an application workflow, you'll want to return a HTTP 302 to your end-user redirecting them to the redirect_url.

Body:

Name Type Description
name string optional The name for the new Connection that will override any automatic name derived from the metadata configuration on the associated API Map.
redirect_url string optional The URL to which the BitScoop API will redirect a third party after they grant permission to your application on a given data provider. This setting will override the configuration on the associated API Map on a per-Connection basis.
endpoints array of string optional A subset of API Map endpoints that the new Connection should have access to. The scope permissions will be automatically calculated from those specified in the API Map endpoint configurations. If no endpoints are specified, it is assumed that all of them are required.
scopes array of string optional Additional required scopes needed for the Connection that may be beyond what is available on the associated API Map.

Example body:

{
	"provider_id": "abc123",
	"name": "My Connection",
	"redirect_url": "https://example.com",
	"endpoints": ["endpointA", "endpointB"],
	"scopes": ["posts", "likes", "photos"]
}

Response:

Name Type Description
id string A UUID4 identifier for the newly created Connection.
redirect_url string The URL to which the end-user should be redirected in order to grant permissions to your app.

Example response:

HTTP/1.1 200 OK

{
	"id": "1234567",
	"redirect_url": "https://auth.example.com/?token=sdflkjfds"
}