-
Notifications
You must be signed in to change notification settings - Fork 0
Play Platform API
The platform API can be used to access to the Play platform resources in an authenticated way. We use token-based mechanisms in conjunction with the Governance service to authenticate the user on each request and authorize it to access to platform resources based on permissions.
The Play Platform API is a REST/JSON API available over HTTP and is described below with the following format:
HTTP Method/Route
GET|POST|PUT|DELETE /resource/path
Request: Input payload (if any)
{
JSON Input
}
Parameters : Input Parameters (if any)
Param A : Value A
Response
Description of the response
HTTP Status Code - Status Text
{
JSON Payload
}
While waiting for a real OAuth2 provider, each Play user has a linked apiToken available in their user account management page. This apiToken is used to authenticate REST calls by setting it as Bearer Token in the HTTP Authorization Header:
Authorization: Bearer YOUR TOKEN
In all the next sections, we describe how to access to protected resources. Authenticating user in each HTTP request is skipped to have a light description.
- Each resource is available at an URL which is available in the API in the resource_url field. Clients can browse the resources URL only if they put right credentials in the HTTP message as described in the previous section.
Streams (also called Topics in the Platform) are resources where data is published by clients and where clients can subscribe to receive notifications when new data is published. Initially based on Web service Notitification specification, the current REST API uses the pubsubhubbub approach which is 'REST-aware'.
HTTP Method/Route
GET /api/v1/topics
Response
Returns a list of available topics the user can subscribe to as JSON array.
HTTP Code 200 - OK
[
{
"name" : "activityEvent",
"ns" : "http://streams.event-processing.org/ids/",
"prefix" : "s",
"resource_url" : "http://API/topics/activityEvent"
},
{
"name" : "MyEvent",
"ns" : "http://streams.event-processing.org/ids/",
"prefix" : "s",
"resource_url" : "http://API/topics/MyEvent"
}
]
HTTP Method/Route
GET /api/v1/topics/{id}
Parameters
id : the topic ID
Response
Returns a topic from its ID (name) as JSON.
HTTP Code 200 - OK
{
"name" : "activityEvent",
"ns" : "http://streams.event-processing.org/ids/",
"prefix" : "s",
"resource_url " : "http://API/topics/activityEvent"
}
Streams (also called Topics in the Platform) are resources where data is published by clients and where clients can subscribe to receive notifications when new data is published. Initially based on Web service Notitification specification, the current REST API uses the pubsubhubbub approach which is 'REST-aware'.
Note: The Stream API uses exactly the same resources as the Topic one since it is the same at the platform level.
HTTP Method/Route
GET /api/v1/streams
Response
Returns a list of available streams the user can subscribe to as JSON array.
HTTP Code 200 - OK
[
{
"resource_url": "http://localhost:8080/play/api/v1/platform/streams/activityEvent",
"id": "http://streams.event-processing.org/ids/activityEvent#stream"
},
{
"resource_url": "http://localhost:8080/play/api/v1/platform/streams/activityEvent2",
"id": "http://streams.event-processing.org/ids/activityEvent2#stream"
}
]
HTTP Method/Route
GET /api/v1/streams/{id}
Parameters
id : the stream name
Response
Returns a stream from its ID (name) as JSON.
HTTP Code 200 - OK
{
"resource_url": "http://localhost:8080/play/api/v1/platform/streams/activityEvent",
"id": "http://streams.event-processing.org/ids/activityEvent#stream"
}
Each user have permissions to read/write/subscribe/publish to streams. This method will check these rights and return status.
HTTP Method/Route
GET /api/v1/streams/{id}/access/{mode}
Parameters
id : the stream name (not an URI) mode: the mode to check (read/write/subscribe/publish)
Response
Returns the stream information if authorized, else 4XX status.
HTTP Code 200 - OK
{
"resource_url": "http://localhost:8080/play/api/v1/platform/streams/activityEvent",
"id": "http://streams.event-processing.org/ids/activityEvent#stream"
}
User can subscribe to Play resources using the subscriptions resource.
When subscribing, the client have to provide a callback URL to receive notifications published in the resource he subscribed. This callback URL has to be set in the input request as defined below.
HTTP Method/Route
POST /api/v1/subscriptions
{
"resource" : "http://streams.event-processing.org/ids/TaxiUCOutNetwork#stream",
"subscriber" : "http://host:port/foo/bar"
}
resource : The resource you want to subscribe to subscriber : HTTP endpoint where messages will be sent according to subscriptions
Response
Returns the subscription result as JSON (Subscription.model) with a subscription ID the client can use to delete the subscription.
HTTP Code 201 - Created
{
"resource" : "http://streams.event-processing.org/ids/TaxiUCOutNetwork#stream",
"subscriber" : "http://host:port/foo/bar",
"subcription_id" : "123456789",
"resource_url" : "http://API/subscriptions/123456789"
}
This will abort the subscription i.e. the callback URL defined in the attached subscription will not receive notifications anymore.
HTTP Method/Route
DELETE /api/v1/subscriptions/{id}
Parameters
id : The ID of the subscription the client wants to remove i.e. unsubscribe.
Response
Returns an HTTP 204 status code if deleted, else an error
HTTP 204 - No Content
Get all the current user subscriptions.
HTTP Method/Route
GET /api/v1/subscriptions
Response
Returns a list of subscriptions (Subscriptions.model) for the current user as JSON array.
HTTP 200 - OK
[
{
"resource" : "http://streams.event-processing.org/ids/TaxiUCOutNetwork#stream",
"subscriber":"http:\/\/host:port\/foo\/bar\/baz",
"subscription_id":"c520227f-3cfa-4f67-b6bf-ee982cbb393e",
"resource_url" : "http://API/subscriptions/c520227f-3cfa-4f67-b6bf-ee982cbb393e"
},
{
"resource" : "http://streams.event-processing.org/ids/MyStream#stream",
"subscriber":"http:\/\/host:port\/foo\/bar",
"subscription_id":"920bf749-391a-4cf0-b97e-7dea183480fd",
"resource_url" : "http://API/subscriptions/920bf749-391a-4cf0-b97e-7dea183480fd"
}
]
Get a subscription.
HTTP Method/Route
GET /api/v1/subscriptions/{id}
Parameters
id : the subscription ID
Response
Returns the subscription (Subscription.model) as JSON if found and if it is the user one.
HTTP 200 - OK
{
"resource" : "http://streams.event-processing.org/ids/TaxiUCOutNetwork#stream",
"subscriber":"http:\/\/host:port\/foo\/bar\/baz",
"subscription_id":"c520227f-3cfa-4f67-b6bf-ee982cbb393e",
"resource_url" : "http://API/subscriptions/c520227f-3cfa-4f67-b6bf-ee982cbb393e"
}
Get patterns published by the user.
HTTP Method/Route
GET /api/v1/patterns
Response
Returns a list of patterns (Pattern.model) which have been published by the user as JSON array.
HTTP 200 - OK
[
{
"data":"...",
"pattern_id":"8494e480-9811-4429-865e-751e0e00b38b",
"resource_url" : "http://API/patterns/8494e480-9811-4429-865e-751e0e00b38b"
},
{
"data":"...",
"pattern_id":"9258b8c7-282b-415b-a5f9-d375082ceab6",
"resource_url" : "http://API/patterns/9258b8c7-282b-415b-a5f9-d375082ceab6"
}
]
Get a pattern from its ID.
HTTP Method/Route
GET /api/v1/patterns/{id}
Parameters
id : the pattern ID
Response
Returns the pattern (Pattern.model) as JSON if found
HTTP 200 - OK
{
"data":"...",
"pattern_id":"9258b8c7-282b-415b-a5f9-d375082ceab6",
"resource_url" : "http://API/patterns/9258b8c7-282b-415b-a5f9-d375082ceab6"
}
Deploy a pattern into the platform.
HTTP Method/Route
POST /api/v1/patterns
Input data is set in the pattern parameter and input Content-Type is defined as application/x-www-form-urlencoded:
pattern=YOURPATTERN
Response
Returns a pattern with its internal ID as JSON.
HTTP 201 - Created
{
"data":"YOURPATTERN",
"pattern_id":"9258b8c7-282b-415b-a5f9-d375082ceab6",
"resource_url" : "http://API/patterns/9258b8c7-282b-415b-a5f9-d375082ceab6"
}
Undeploy a pattern which is already deployed.
HTTP Method/Route
DELETE /api/v1/patterns/{id}
Parameters
id : the ID of the pattern to undeploy
Response
Returns an HTTP status 204 if deleted, else error...
HTTP 204 - No Content
HTTP Method/Route
POST /api/v1/patterns/analyze
Input data is set in the pattern parameter and input Content-Type is defined as application/x-www-form-urlencoded:
pattern=YOURPATTERN
Response
Returns an HTTP status 200 is analyze is OK, else error
HTTP 200 - OK
Publish a new message to a resource into the platform.
HTTP Method/Route
POST /api/v1/publish
Input data is passed into the HTTP payload as application/x-www-form-urlencoded in order to be able to push any type of message.
Where input parameters are:
reource : the resource ID where you want to publish message into. The user must be authorized to push data to this resource. If not, the API will send back an error. message : the message you want to publish into the resource
Response
Returns HTTP 200 OK code if pusblish is OK
HTTP 200 - OK
Here are some cURL samples to interact with the REST API:
Get the topics for the authenticated user:
curl --header "Authorization: Bearer YOUR-API-KEY" http://localhost:8080/play/api/v1/platform/topics
Get the subscriptions for the authenticated user:
curl --header "Authorization: Bearer YOUR-API-KEY" http://localhost:8080/play/api/v1/platform/subscriptions
Subscribe to some notifications
curl -v -X POST --header "Authorization: Bearer YOUR-API-KEY" --header "Content-Type: application/json"\
--data "{'resource' : 'http://streams.event-processing.org/ids/activityEvent#stream', 'subscriber' : 'http://host:port/foo/bar/123456'}"\
http://localhost:8080/play/api/v1/platform/subscriptions
Get the patterns for the authenticated user:
curl --header "Authorization: Bearer YOUR-API-KEY" http://localhost:8080/play/api/v1/platform/patterns
Deploy a new pattern
curl -v --header "Authorization: Bearer YOUR-API-KEY" \
--data "pattern=YOUR PATTERN"\
http://localhost:8080/play/api/v1/platform/patterns
Publish a message to a resource:
curl -v --header "Authorization: Bearer YOUR-API-KEY" \
--data "resource=http://foo#stream"\
--data "message={'foo' : 'bar'}"\
http://localhost:8080/play/api/v1/platform/publish
TODO
- The Platform API is defined in the governance-platform-userapi module at https://github.com/play-project/play-governance/tree/master/governance-platform-userapi
- The Platform API implementation is defined in the governance-platform-userservice module at https://github.com/play-project/play-governance/tree/master/governance-platform-userservice
API is bundled into the final governance Web Archive (WAR) generated in the governance-war module.