TIBCO Mashery® IO Docs Examples

Table of Contents

• Introduction
• Example #1 - API config that uses basic key authentication:
• Example #2 - API config that uses basic key authentication with signatures (signed call).
• Example #3 - Foursquare API config that uses 3-legged OAuth 2.0  
• Example #4 - Full Explanation of each field in an example API configuration  
• Example #5 - Request Bodies, Arrays, & Objects

Introduction

This article is designed to help provide a better understanding of how to use TIBCO Mashery^® IO Docs through examples. Each of the fields in the example is explained.

Example #1 - API config that uses basic key authentication:

 {     "name": "Lower Case API",     "title": "Lower Case API",     "protocol": "rest",     "basePath": "http://api.lowercase.sample.com",     "publicPath": "/v1",     "auth": {         "key": {             "param": "key",             "location": "query"         }     },     "headers": {         "Accept": "application/json",         "Foo": "bar"     },     ...

Explanation

Line:

1 - "name" key value is a string that holds the name of the API that is used in the template output.

2 - "title" key value is a string that will be displayed in the API explorer API selection drop-down.

3 - "protocol" key value is either rest or soap

4 - "basePath" key value is the host path of the API calls

5 - "publicPath" key value is the full path prefix prepended to all method URIs. This value often includes the version in RESTful APIs.

Ex: "/v1"

Note - In Example #3 below, there is also "privatePath" which is used for endpoints behind protected resources.

6 - "auth" container holds the authorization information. If absent, API requires no authorization.

7 - The key value that describes the auth method. Valid values can be:

• "key" = simple API key in the URI
• "oauth" = OAuth 1.0/2.0
• "" = no authentication

8 - "param" key value is the name of the parameter that is added to an API request when the "auth" key value from (6) is set to "key".

9 - "location" (optional) key-value sets where the api key will go in the request. Defaults to "query". supported values: "query" and "header".

10 - "headers" object contains key value pairs of HTTP headers that will be sent for each request for API. These are static key/value pairs.

Example #2 - API config that uses basic key authentication with signatures (signed call).

 {     "name": "Lower Case API",     "title": "Lower Case API",     "protocol": "rest",     "basePath": "http://api.lowercase.sample.com",     "publicPath": "/v1",     "auth": {         "key": {             "param": "key",             "signature": {                 "type": "signed_md5",                 "param": "sig",                 "digest": "hex",                 "location": "header"             }         }     },     ...

Explanation

Line:

1 - "name" key value is a string that holds the name of the API that is used in the template output.

2 - "title" key value is a string that will be displayed in the API explorer API selection drop-down.

3 - "protocol" key value is either rest or soap

4 - "basePath" key value is the host path of the API calls

5 - "publicPath" key value is the full path prefix prepended to all method URIs. This value often includes the version in RESTful APIs. 

Ex: "/v1"

Note - In Example #3 below, there is also "privatePath" which is used for endpoints behind protected resources.

6 - "auth" container holds the authorization information. If absent, API requires no authorization.

7 - The key value that describes the auth method. Valid values can be:

• "key" = simple API key in the URI
• "oauth" = OAuth 1.0/2.0
• "" = no authentication

8 - "param" key value is the name of the parameter that is added to an API request when the "auth" key value from (6) is set to "key".

9 - "signature" is a JSON object that contains the details about the API call signing requirements. The signature routine coded in app.js is a hash of the string concatenation of API key, API key secret, and timestamp (epoch).

10 - "type" key value is either signed_md5 or signed_sha256. More signature methods are available with crypto.js, but have not been included in the code as options.

11 -  "param" key value is the name of the parameter that is added to an API request that holds the digital signature.

12 - "digest" key value is the digest algorithm that is used. Values can be hex, base64 or binary.

13 - "location" (optional) key-value sets where the signature will go in the request. Defaults to "header".

Example #3 - Foursquare API config that uses 3-legged OAuth 2.0

 {     "name": "Foursquare (OAuth 2.0 Auth Code)",     "protocol": "rest",     "basePath": "https://api.foursquare.com",     "privatePath": "/v2",     "auth": {         "oauth": {             "version": "2.0",             "type": "authorization-code",             "base_uri": "https://foursquare.com/",             "authorize_uri": "oauth2/authenticate",             "access_token_uri": "oauth2/access_token_uri",             "token": {                 "param": "oauth_token",                 "location": "query"             }         }     },     ...

Line:

1 - "name" key value is a string that holds the name of the API that is used in the template output.

2 - "protocol" key value is either rest or soap

3 - "basePath" key value is the host path of the API calls

4 - "privatePath" key value is the path prefix prepended to all method URIs for OAuth-protected method resources. This value is most often the version in RESTful APIs.

Ex: "/v1", "/1", etc.

5 - "auth" container holds the authorization information. If absent, API requires no authorization.

6 - "oauth" key value is a JSON object that contains the OAuth implementation details for this API.

7 - "version" key value is the OAuth version. OAuth 1.0 and 2.0 are supported.

8 - "type" key value is the OAuth 2 authorization flow used for this API.

Valid values are "authorization-code", "client_credentials", and "implicit", named for each grant found here: "http://tools.ietf.org/html/rfc6749".

9 - "base_uri" key value is the base website URL used in the OAuth 2 dance. It is required.

10 - "authorize_uri" key value is the url string used to retrieve the authorization token in the "authorization-code" OAuth 2 flow. This is not necessary in any other OAuth 2 flow.

11 - "access_token_uri" key value is the url string used to retrieve the access (Bearer) token in any OAuth 2 flow. This is required in all OAuth 2 flows.

12 -"token" container instructs I/O Docs were to use the access/bearer token on requests. If the "location" is set as the default token name when making calls with the access token in the url query parameters. Not required if "access_token" is used.

13 - "param" is the parameter name for an access token. This is valid only if the location value is "query"

14 - "location" (optional) key value that sets where the bearer token will go. Acceptable values are: "header" and "query". If set to header, I/O Docs will follow the "Authorization: Bearer XXX" pattern. If set to "query", the name of the key will be dictated by the "param" value on line 13.

Additional Note: All redirect URIs for the Foursquare API & your Foursqare app must be set through the Foursquare developer site. For the iodocs Foursquare API test, these URIs are: "http://localhost:3000/foursquare", "http://localhost:3000/oauth2Success/foursquare"

For the Rdio API test, beta access to their new API is necessary. The site for the beta API is: "http://www.rdio.com/developers/"

Example #4 - Full Explanation of each field in an example API configuration

 {     "name": "Lower Case API",     "protocol": "rest",     "basePath": "http://api.lowercase.sample.com",     "resources": {         "User Resources": {             "methods": {                 "showUsers": {                     "name": "users/show",                     "description": "Returns extended user information",                     "httpMethod": "GET",                     "path": "/users/show.json",                     "parameters": {                         "user_id": {                             "title":"user_id",                             "required":true,                             "default":"",                             "type":"string",                             "description":"The ID of the user"                         },                         "cereal": {                             "title": "cereal",                             "required": true,                             "default": "fruitscoops",                             "type": "string",                             "enum": ["fruitscoops","sugarbombs","frostedteeth"],                             "description": "The type of cereal desired."                         },                         "skip_status": {                             "title": "skip_status",                             "required": false,                             "default": "false",                             "type":"boolean",                             "description":"If true, status not included."                             "location": "header"                         },                         "include_status": {                             "title": "include_status",                             "required": false,                             "default": false,                             "type": "boolean",                             "description": "If true, status included."                             "booleanValues": ["yes","no"]                         },                         "review": {                             "title": "review",                             "required": false,                             "default": "",                             "type": "textarea",                             "description": "The user's review to submit."                         }                     }                 }             }         }     }

Explanation

Line:

1 - "name" key value is a string that holds the name of the API that is used in the Jade template output. Also true in apiconfig.json.

2 - "protocol" key value is either rest or soap

3 - "basePath" key value is the host path of the API calls

4 - "resources" JSON container. Methods are grouped into resources.

5 - The first resource.

6 - "methods" key value is an array of JSON objects (each one being a method)

7 - The first method.

8 - "name" key value is a string that is displayed via the view template. The name of the method.

9 - "description" key value is a short description of the method.

10 - "httpMethod" key value can be either GET, POST, DELETE or PUT (all caps)

11 - "path" key value is the path to the method that is appended to the baseURL and the public/private path.

12 - "parameters" key value is a JSON object containing the parameters

13 - The first parameter.

14 - "title" key value is a string that contains the name of the parameter.

15 - "required" key value is either true or false.

16 - "default" key value is a string, containing a default value that will be automatically populated onto the form.

17 - "type" key value can be an arbitrary string that describes the variable type; however, the value is boolean or enumerated a drop-down (select) box will appear.

18 - "description" key value is a string, containing the description of the parameter.

25 - "enum" key value is an array of enumerated values that will render a drop-down (select box) on the form.

32 - "type" key value is a boolean that will render a drop-down (select box) on the form for true and false.

24 - "location" (optional) key-value determines where the parameter will go. Can be "query" or "header". Default to "query".

43 - "booleanValues" is an array of [true, false] alternatives that will instead populate the drop-down box.

49 - "type" key value is textarea that will render a textarea box, a multi-line text input control.

Example #5 - Request Bodies, Arrays, & Objects

 {     "name": "Lower Case API",     "protocol": "rest",     "basePath": "http://api.lowercase.sample.com",     "schemas": {         "showUsers": {             "properties": {                 "bodyParam": {                     "title":"bodyParam",                     "required":true,                     "default":"",                     "type":"string",                     "description":"An example parameter in the body"                 },                 "arrayExample": {                     "type": "array",                     "items": {                         "title":"arrayExample",                         "required": true,                         "default": "foobar",                         "type":"string",                         "description":"An array in the body."                     }                 },                 "objectExample": {                     "type": "object",                     "properties": {                         "element1": {                             "title": "element1",                             "required":false,                             "type":"string",                             "description": "An element in a JSON object.",                             "default": "el1"                         },                         "element2": {                             "title": "element2",                             "required":false,                             "type":"string",                             "description": "Second element in a JSON object.",                             "default": "el2"                         },                         "subObjectEx": {                             "type": "object",                             "properties": {                                 "element3": {                                     "title": "element3",                                     "required":false,                                     "type":"string",                                     "description": "An element within an object within an object.",                                     "default": "el3"                                 }                             }                         }                     }                 }             }         }     },     "resources": {         "User Resources": {             "methods": {                 "showUsers": {                     "name": "users/show",                     "description": "Returns extended user information",                     "httpMethod": "GET",                     "path": "/users/show.json",                     "request": {                         "$ref": "showUsers"                     },                     "parameters": {                         "user_id": {                             "title":"user_id",                             "required":true,                             "default":"",                             "type":"string",                             "description":"The ID of the user"                         }                     }                 }             }         }     }

Explanation

Line:

4 - "schemas" JSON object. Contains the parameters that will go into the request body for all methods.

5 - The first method to contain a request body.

6 - "properties" JSON object containing the parameters that will go into the request body.

7 - The first request body parameter. The format is the same as in "resources"

14 - An array parameter. An array parameter can add as many values to the parameter as necessary. The default location for an array will always be "body".

15 - "type" key value set to an array. Necessary for the array functionality to work.

16 - "items" JSON object that contains the parameter information. The format is consistent with resources parameters.

24 - A JSON object parameter.

25 - "type" key value set to object. Necessary for the object functionality to work.

26 - "properties" JSON object containing the parameters that will go into the object.

41 - An object embedded within an object.

66 - "request" JSON object holds the reference to the request body parameters

67 - "$ref" key value is the reference to the same string in "schemas"