REST API Requests and Responses

Submission Methods

API requests can be submitted using the following HTTP methods:

Supported Formats

Response formats

The Storyteller REST API supports the following response formats:

  • JSON (default)
    To use JSON format, add the following information to your request header:
    Accept: application/json
  • XML
    To use XML format, add the following information to your request header:
    Accept: application/xml
Request Formats

The Storyteller REST API supports the following request formats:

  • JSON
    To use JSON format for your request body, add the following information to your request header:
    Content-Type: text/json
  • XML
    To use XML format for your request body, add the following information to your request header:
    Content-Type: text/xml
    XML data in the request body must adhere to the Storyteller REST API XML Schema.

Pagination

Storyteller limits the number of results that can be returned in a single response in order to ensure optimal performance. Paging is controlled using the Offset and Limit parameters:

  • Offset (optional): Defines the paging offset (that is, index) at which the results start. Offset the default is 0.
  • Limit (optional): Defines the number of items (projects, artifacts, etc) to retrieve per query. This parameter can be set to an integer. The default is 100. The minimum value is 1 and the maximum value is 500.

When pagination is in effect, response will always be returned with an HTTP status code of 206: Partial Content. When this happens, the response header always contains a content-range parameter that indicates the items included in the response and the total number of matches. If the total number of matches is unknown, an asterisk appears instead. For example, the following response header indicates that there are a total of 122 users and the response includes users at position 13 to 15.

{'content-length': '822', 'expires': '-1', 'server': 'Blueprint', 'content-range': 'users 13-15/122', 'pragma': 'no-cache', 'cache-control': 'no-cache', 'date': 'Sat, 04 May 2013 11:59:23 GMT', 'content-type': 'application/json; charset=utf-8'}
Pagination Examples

This request returns the first 50 artifacts (that is, artifacts 0 - 49):

https://production.blueprintcloud.com/api/v1/projects/220870/artifacts?Offset=0&Limit=50

This request returns the next 100 artifacts (that is, artifacts 50 - 149):

https://production.blueprintcloud.com/api/v1/projects/220870/artifacts?Offset=50&Limit=100

This request returns the next 25 artifacts (that is, artifacts 150 - 174):

https://production.blueprintcloud.com/api/v1/projects/220870/artifacts?Offset=150&Limit=25