Select Git revision
blendb-api-v1.raml
-
Eduardo L. Buratti authoredEduardo L. Buratti authored
blendb-api-v1.raml 15.56 KiB
#%RAML 0.8
title: BlenDB API
version: v1
baseUri: http://blendb.c3sl.ufpr.br/api/{version}
mediaType: application/json
securitySchemes:
- oauth_2_0:
description: |
OAuth2 is a protocol that lets apps request authorization to
private details in the system while avoiding the use of passwords.
This is preferred over Basic Authentication because tokens can be
limited to specific types of data, and can be revoked by users at
any time.
type: OAuth 2.0
describedBy:
headers:
Authorization:
description: |
Used to send a valid OAuth 2 access token. Do not use
together with the "access_token" query string parameter.
type: string
queryParameters:
access_token:
description: |
Used to send a valid OAuth 2 access token. Do not use
together with the "Authorization" header.
type: string
responses:
401:
description: |
Bad or expired token. This can happen if access token
has expired or has been revoked by the user.
body:
application/json:
example: |
{
id: "invalid_oauth_token",
message: "Bad or expired token. This can happen if access token has expired or has been revoked by the user."
}
403:
description: |
Bad OAuth2 request (wrong consumer key, bad nonce,
expired timestamp, ...).
body:
application/json:
example: |
{
id: "invalid_oauth_request",
message: "Bad OAuth2 request (wrong consumer key, bad nonce, expired timestamp, ...)."
}
settings:
authorizationUri: http://simmc.c3sl.ufpr.br/oauth/authorize
accessTokenUri: http://simmc.c3sl.ufpr.br/oauth/access_token
authorizationGrants: [ code, token ]
scopes:
- "user"
- "user:email"
resourceTypes:
- base:
get?: &common
responses:
403:
description: API rate limit exceeded.
headers:
X-RateLimit-Limit:
type: integer
X-RateLimit-Remaining: type: integer
X-RateLimit-Reset:
type: integer
body:
application/json:
example: |
{
id: "too_many_requests",
message: "API Rate limit exceeded."
}
post?: *common
put?: *common
delete?: *common
- collection:
type: base
get?:
description: |
List all of the <<resourcePathName>> (with optional
filtering).
responses:
200:
description: |
A list of <<resourcePathName>>.
body:
application/json:
schema: <<collectionSchema>>
example: <<collectionExample>>
post?:
description: |
Create a new <<resourcePathName|!singularize>>.
responses:
201:
description: |
Sucessfully created a new
<<resourcePathName|!singularize>>.
headers:
Location:
description: |
A link to the newly created
<<resourcePathName|!singularize>>.
type: string
409:
description: |
Failed to create a new
<<resourcePathName|!singularize>> because a conflict
with an already existing
<<resourcePathName|!singularize>> was detected.
body:
application/json:
example: |
{
"id": "already_exists",
"message": "The <<resourcePathName|!singularize>> could not be created due to a conflict with an already existing <<resourcePathName|!singularize>>."
}
- item:
type: base
get?:
description: |
Return a single <<resourcePathName|!singularize>>.
responses:
200:
description: |
A single <<resourcePathName|!singularize>>.
body:
application/json:
schema: <<itemSchema>>
example: <<itemExample>>
404:
description: |
The <<resourcePathName|!singularize>> could not be found.
body:
application/json:
example: |
{
"id": "not_found",
"message": "The <<resourcePathName|!singularize>> could not be found."
}
put?:
description: |
Update a <<resourcePathName>>.
responses:
204:
description: |
The <<resourcePathName|!singularize>> was updated.
404:
description: |
The <<resourcePathName|!singularize>> could not be
found.
body:
application/json:
example: |
{
"id": "not_found",
"message": "The <<resourcePathName|!singularize>> could not be found."
}
409:
description: |
Failed to update the <<resourcePathName|!singularize>>
because a conflict with another
<<resourcePathName|!singularize>> was detected.
body:
application/json:
example: |
{
"id": "already_exists",
"message": "Failed to update the <<resourcePathName|!singularize>> because a conflict with another <<resourcePathName|!singularize>> was detected."
}
patch?:
description: |
Partially update a <<resourcePathName>>.
responses:
204:
description: |
The <<resourcePathName|!singularize>> was updated.
404:
description: |
The <<resourcePathName|!singularize>> could not be
found.
body:
application/json:
example: |
{
"id": "not_found",
"message": "The <<resourcePathName|!singularize>> could not be found."
}
409:
description: |
Failed to update the <<resourcePathName|!singularize>>
because a conflict with another
<<resourcePathName|!singularize>> was detected.
body:
application/json:
example: |
{
"id": "already_exists",
"message": "Failed to update the <<resourcePathName|!singularize>> because a conflict with another <<resourcePathName|!singularize>> was detected."
}
delete?:
description: | Removes a <<resourcePathName>>.
responses:
204:
description: |
The <<resourcePathName|!singularize>> was removed.
404:
description: |
The <<resourcePathName|!singularize>> could not be
found.
body:
application/json:
example: |
{
"id": "not_found",
"message": "The <<resourcePathName|!singularize>> could not be found."
}
- index:
type: base
get?:
description: |
Return an index on the <<resourcePathName>> collection.
responses:
200:
description: |
An index on the <<resourcePathName>> collection.
body:
application/json:
traits:
- paged:
queryParameters:
page:
description: Specify the page that you want to retrieve
type: integer
default: 1
example: 1
per_page:
description: The number of items to return per page
type: integer
minimum: 1
maximum: 50
default: 10
example: 20
- searchable:
queryParameters:
query:
description: |
Query string that filters the data returned for your
request.
type: string
- filtered:
queryParameters:
filters:
description: |
Filters that restrict the data returned for your request.
type: string
- projectable:
queryParameters:
fields:
description: |
Fields to be returned.
type: string
/metrics:
description: |
A Metric represents a statistic that can be queried to generate reports.
This collection allows the user to list all the metrics available in the
system and their descriptions.
securedBy: [ null, oauth_2_0 ] get:
/dimensions:
description: |
A Dimension allows the data to be aggregated by one or more columns.
This collection allows the user to list all the dimensions available in
the system and their descriptions.
securedBy: [ null, oauth_2_0 ]
get:
/data:
description: |
This is the main part of the API. You may query it for report
data by specifying metrics (at least one). You may also supply
additional query parameters such as dimensions, filters, and
start/end dates to refine your query.
type: base
get:
is: [ filtered ]
queryParameters:
metrics:
description: |
A list of comma-separated metrics.
type: string
required: true
example: "met:daysSinceLastContact,met:estimatedNetworkBandwidth"
dimensions:
description: |
A list of comma-separated dimensions.
type: string
required: true
example: "dim:project,dim:point"
start-date:
description: |
Start date for fetching data. Requests can specify a
start date formatted as YYYY-MM-DD, or as a relative date
(e.g., today, yesterday, or NdaysAgo where N is a positive
integer).
type: string
required: false
pattern: "[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)"
example: 7daysAgo
end-date:
description: |
End date for fetching data. Requests can specify a
end date formatted as YYYY-MM-DD, or as a relative date
(e.g., today, yesterday, or NdaysAgo where N is a positive
integer).
type: string
required: false
pattern: "[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)"
example: yesterday
filters:
description: |
Filters that restrict the data returned for your request.
type: string
example: "dim:location(4).id%3D%3D10723"
sort:
description: |
A list of comma-separated dimensions and metrics
indicating the sorting order and sorting direction for
the returned data.
type: string
example: "dim:project"
responses:
200:
description: |
Query successfully executed. Data is returned in a table format.
body:
application/json: 400:
description: |
The supplied query is invalid. Specified metric or dimension
doesn't exist, incorrect formatting for a filter, unacceptable
date range, etc.
body:
application/json:
example: |
{
"id": "metric_not_found",
"message": "The specified metric 'met:electricCharge' could not be found."
}
/collect/{sourceName}:
description: |
This API may be used to send data to the monitoring system. All data
sent must be identified with a sourceName, i.e. "gesacNetworkBandwidth".
type: base
uriParameters:
sourceName:
description: An identifying name for the data that is being collected.
type: string
minLength: 4
maxLength: 64
pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
post:
body:
application/json:
responses:
200:
description: |
Data has been successfully received and stored by the server.
400:
description: |
An error has been found in your request. You may review your
request and the data that is being sent and try again later.
body:
application/json:
example: |
{
"id": "type_error",
"message": "Invalid type for attribute \"memory\"."
}