The TIBCO Platform is a real-time, composable data platform that will bring together an evolving set of your TIBCO solutions - and it's available now!
A chart showing the TIBCO Platform vision
Jump to content
Articles
Read more about TIBCO use cases, product features, capabilities and more
  • 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 an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

×
×
  • Create New...