Introducing the all-new TIBCO Community site!

For current users, please click "Sign In" to reset your password and access the enhanced features. If you're a first-time visitor, we extend a warm welcome—click "Sign Up" to become a part of the TIBCO Community!

If you're seeking alternative community sites, explore ibi, Jaspersoft, and Spotfire.

Jump to content
  • TIBCO Mashery® IO Docs Examples


    Manoj Chaurasia

    Table of Contents


    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"


    User Feedback

    Recommended Comments

    There are no comments to display.


×
×
  • Create New...