TIBCO Mashery® I/O Docs Configuration Guide

Table of Contents

• About this Guide
• Introduction
• Overview
• Prerequisites and Enablement Overview
• Prerequisites
• Enablement Overview
• Top-Level Configuration Overview
• I/O Docs Definitions Overview
• Global I/O Docs Page Settings
• Adding I/O Docs Definitions
• Markdown support in I/O Docs
• I/O Docs Definition Schema Details
• JSON Schema Overview
• JSON Object Property Details
• Example #1 ? Key Only Auth
• Example #2 ? Key, Secret and Signature Auth
• Example #3 ? OAuth 2.0 API
• Example #4 ? Google OAuth 2.0 API
• Example #5 ? Post Body

About this Guide

Introduction

This guide describes how to configure Mashery I/O Docs using the Administration Dashboard. Mashery I/O Docs is an interactive API exploration and testing tool that runs on your Developer Portal. It enables your developer partners to perform API calls from within the documentation with their own API keys with described form-based parameter inputs fields and easy-to-read color-coded and formatted payload outputs.

For some APIs, I/O Docs may serve as a full-on replacement for traditional long-form documentation. However, it can also serve as a useful compliment to regular documentation, especially in cases of APIs that have more advanced authentication and request methods.

Overview

The Mashery I/O Docs Configuration Guide is divided into the following chapters:

• Prerequisites and Enablement Overview - Provides you with a quick overview of the requirements and the process to activate I/O Docs on your Developer Portal via the Administration Dashboard.
• Top-Level Configuration Overview - A high-level view of the global Developer Portal configuration settings and I/O Docs Definitions
• I/O Docs Definition JSON Schema - A deep dive into the description schema that describes your resources, methods and parameters. This schema definition is used to render the interactive docs.

See also:

• I/O Docs Configuration Examples
• Using jQuery-UI Controls in IO Docs

Prerequisites and Enablement Overview

Prerequisites

I/O Docs is available on all default Mashery deployments, meaning that options to enable and configure I/O Docs are available in the Administrative Dashboard. If for any reason the options to enable and configure I/O Docs are not visible, please contact your Client Service Manager for more information.

Enablement Overview

To enable I/O Docs:

1. Access to the Mashery Admin Dashboard.
2. Enable the I/O Docs Content Module by navigating to Portal Settings > Content and checking the box adjacent to Enable I/O Docs:

    

   

3. Click Save.

After completing these steps, I/O Docs is enabled. The URL for I/O Docs on your portal is: http://devhost.devdomain.com/io-docs, for example, if your portal URL is http://developer.acme.com, then the URL for I/O Docs would be http://developer.acme.com/io-docs. 

Top-Level Configuration Overview

I/O Docs Definitions Overview

Definitions for I/O Docs are used to generate the rendered I/O Docs interface, including the groups of resources, methods, and parameters. Definitions are associated with APIs configured in the API Settings section of the Administration Dashboard. An API is allowed only one I/O Docs definition.

Note that although an I/O Docs definition is associated with an API, it is functionally separate. This means that you can freely configure your I/O Docs definition to highlight only certain resources, methods, or parameters of your choice.

The definitions are simple JSON objects modeled after the Google Discovery Document format (GDDF). The schema format has been extended to address authentication and signature methods. More detailed information about the schema can be found in Chapter 4.

Global I/O Docs Page Settings

You can provide a page title header and description that appears at the top of every rendered IO Docs page.  These attributes can be set by following these steps:

1. Access the Mashery Admin Dashboard
2. Navigating to the Design > I/O Docs section
3. Click IO Docs Settings in the top right-hand corner of the page.
4. Edit the fields to add/change the Page Title and Description
5. Click Save.

Adding I/O Docs Definitions

If you have enabled I/O Docs by following the previous directions, the next step is to add definitions to one or more APIs.

To add I/O Docs definitions:

1. Access the Mashery Admin Dashboard
2. Navigating to the Design > I/O Docs section

    

   

3. Select the API you want to add or modify to display the IO Docs definition.
4. Edit the skeleton JSON schema that describes the entire API?s set of resources, methods, and parameters that you wish to expose via I/O Docs.

    

   The JSON format details can be found in the next section.

5. Click Save JSON Definition:

Markdown support in I/O Docs

I/O docs (PHP version) supports Markdown syntax to be used within the description properties at the API, method, and parameter level. There are however some limitations with using markdown in I/O Docs JSON based definitions.

I/O Docs Markdown Known Limitations and Issues

Due to the nature of the I/O docs view implementation, the API description supports a subset of the Markdown syntax. Specifically, links and tags that utilize quotes are not supported at the API description level and only supported at the resource level, within the method and parameter descriptions level. For example:

 "description": "This is [an example](http://example.com) inline link."

Other limitations

• Links, Images, and Tables are not supported at the API description level (at the top of the page).
• Heading level 2 (H2) renders as a drop-down list when used at the API description level (see image below)
• Bulleted lists render as indented items without bullets.
• Automatic links are not supported; this syntax will not render a link in I/O docs: <http://example.com/>

Markdown uses blank lines to indicate that a "new line" is desired in the resulting HTML. A blank line is any line that looks like a blank line ? a line containing nothing but spaces or tabs is considered blank. To represent this Markdown syntax correctly within the I/O docs JSON definition requires adding a "\n" before the markdown in certain cases. For example, the following code will show something as Heading level 1 (H1):

 "\n# Level 3 Header" 

 "\n# Level 3 Header"

will show as Level 3 Header in I/O Docs

I/O Docs Definition Schema Details

JSON Schema Overview

A schema is a JSON object containing top-level API properties along with resources, methods and parameters that describe how API requests are formed and transmitted. The Mashery I/O Docs Definition Schema is based in part on the Google Discovery Document format. Some properties within the GDDF are disregarded by the I/O Docs schema processor and will not be referenced below or in the examples. The GDDF has been extended to address authentication and signature methods.

JSON Object Property Details

See IO Docs Definition for property descriptions.

 {      "name":"value",    "version":"value",    "title":"value",    "description":"value",    "protocol":"rest",    "basePath":"value",    "auth":{         "key":{            "param":"value",          "location":"value",          "secret":{               "param":"value",             "type":"value"          }       },       "basicAuth":"value",       "oauth":{            "version":"value",          "base_uri":"value",          "authorize_uri":"value",          "access_token_uri":"value",          "auth_flows":[               "value"          ],          "options":{             }       }    },    "resources":{         "value":{            "methods":{               "value":{                  "path":"value",                "httpMethod":"value",                "description":"value",                "parameters":{                     "value":{                        "description":"value",                      "default":"value",                      "required":"value",                      "enum":[                           "value"                      ],                      "enumDescriptions":[                           "value"                      ],                      "location":"value"                   }                }             }          }       }    } }

Example #1 ? Key Only Auth

This is an example of an I/O Docs Definition for an API that uses key-based authorization,

where the key is passed in a query string parameter named "api_key".

Example #1 - I/O Docs Definition

 {      "name":"Example #1 API",    "version":"1.0",    "title":"The Key Only Auth API",    "description":"The first example features API key based authentication only.",    "protocol":"rest",    "basePath":" http://api.example1.com/v1",    "auth":{         "key":{            "param":"api_key",          "location":"query"       }    },    "resources":{         "Product Methods":{            "methods":{               "Get Products":{                  "path":"/products.:format",                "httpMethod":"GET",                "description":"Get all products in our database",                "parameters":{                     ":format":{                        "type":"string",                      "required":true,                      "default":"json",                      "description":"Output format as JSON or XML",                      "enum":[                           "json",                         "xml"                      ],                      "location":"pathReplace"                   }                }             }          }       }    } }

Example #1 - I/O Docs Rendered

Example #2 ? Key, Secret and Signature Auth

This is an example of an I/O Docs definition for an API that uses key-based authorization

with an MD5 hash signature. The string that is hashed is a concatenation of the following

values: API key, secret, epoch (POSIX time).

 {      "name":"Example #2 API",    "version":"1.0",    "title":"The Key, Secret and Signature Auth API",    "description":"This second example features key, secret and signature.",    "protocol":"rest",    "basePath":"http://api.example2.com/v2",    "auth":{         "key":{            "param":"api_key",          "location":"query",          "secret":{               "param":"sig",             "type":"signed_md5"          }       }    },    "resources":{         "People":{            "methods":{               "personInfo":{                  "path":"/personInfo/:personId",                "httpMethod":"GET",                "description":"Returns person record. ",                "parameters":{                     ":personId":{                        "type":"int",                      "required":true,                      "default":"",                      "description":"Numerical (int) ID of a person",                      "location":"pathReplace"                   },                   "format":{                        "type":"string",                      "required":true,                      "default":"json",                      "description":"Output format as JSON or XML",                      "enum":[                           "json",                         "xml"                      ],                      "location":"query"                   }                }             }          }       }    } }

Example #2 - I/O Docs Rendered

Example #3 ? OAuth 2.0 API

This is an example of an I/O Docs Definition for an API that uses OAuth 2.0 and the

authentication code flow. Additional options for scope are also included in this

configuration. OAuth 1.0 and 1.0a are not supported by I/O Docs.

Example #3 - I/O Docs Definition

 {      "name":"Example #3 API",    "version":"1.0",    "title":"The OAuth 2 API",    "description":"This third example features OAuth 2.0",    "protocol":"rest",    "basePath":" http://api.example3.com/v3",    "auth":{         "oauth":{            "version":"2.0",          "auth_flows":[               "auth_code"          ],          "base_uri":"http://api.example3.com",          "authorize_uri":"/oauth/authorize",          "access_token_uri":"/oauth/token",          "access_token_location":"header",          "options":{               "authorize":{                  "scope":[                     "read",                   "write",                   "execute"                ]             }          }       }    },    "resources":{         "Account Resources":{            "methods":{               "getAccount":{                  "path":"/getAccount/:accountID",                "httpMethod":"GET",                "description":"Fetches account information",                "parameters":{                     ":accountID":{                        "type":"int",                      "required":true,                      "default":"",                      "description":"The account number",                      "location":"pathReplace"                   }                }             }          }       }    } }

Example #3 - I/O Docs Rendered

Example #4 ? Google OAuth 2.0 API

Example #4 - I/O Docs Definition

 {      "name":"Google APIs",    "version":"1.0",    "title":"The Google APIs That Use OAuth 2.0",    "description":"This fourth example features the Google APIs that use OAuth 2.0 for authentication.",    "protocol":"rest",    "basePath":"https://www.googleapis.com",    "auth":{         "oauth":{            "version":"2.0",          "base_uri":"https://accounts.google.com",          "auth_flows":[               "auth_code",             "implicit"          ],          "authorize_uri":"/o/oauth2/auth",          "access_token_uri":"/o/oauth2/token",          "options":{               "authorize":{                  "scope":[                     "https://www.googleapis.com/auth/calendar"                ],                "access_type":"online",                "approval_prompt":"force"             },             "auto_exchange_auth_code":true          }       }    },    "resources":{         "Google Calendar":{            "methods":{               "Get Events by Calendar ID":{                  "description":"Get Events by Calendar ID",                "httpMethod":"GET",                "path":"/calendar/v3/calendars/:calendar_id/events",                "parameters":{                     ":calendar_id":{                        "required":"true",                      "default":"",                      "type":"string",                      "description":"The Calendar ID to fetch",                      "location":"pathReplace"                   }                }             }          }       }    } }

Example #4 - I/O Docs Rendered

Example #5 ? Post Body

This is an example of an I/O Docs Definition for an API that uses key-based authorization,

where the key is passed in a query string parameter named "api_key".

Example #5 - I/O Docs Definition

 {      "name":"acme daily deal api definition",    "version":"1.0",    "title":"Acme Daily Deal API",    "description":"This Daily Deal API is used to find the most current daily deals.",    "protocol":"rest",    "basePath":"http://api.acmeapparelstore.com/",    "auth":{         "key":{            "param":"apikey",          "location":"query"       }    },    "resources":{         "Review Daily Deal":{            "methods":{               "PostDailyDealReview":{                  "path":"deal",                "httpMethod":"POST",                "description":"Submit a review on the the most current Daily Deal.",                "parameters":{                     "reviewBody":{                        "description":"Some well-formed JSON",                      "default":"{ \"some\": \"well-formed\", \"json\": \"string\" }",                      "type":"textarea",                      "required":true,                      "location":"body"                   },                   "Content-Type":{                        "type":"string",                      "required":"true",                      "description":"Content type of the payload",                      "default":"application/json",                      "location":"header"                   }                }             }          }       }    } }

Example #5 - I/O Docs Rendered