Suggested Modifications to the Swagger Format

Motivation

Swagger is a great format for describing your API, creating very pretty and useful documentation pages. For our purposes of using it to power connection factories that effortlessly connect to those APIs we need a little bit more detail, though, to make explicit what's already implicitly contained.

For example, we want to wrap that one parameter that is the API key that needs to be specified in all operations into an authentication description paragraph, so that it can even be specified on a configuration level and wouldn't need to be passed in with every call.

Other suggested extensions cover cases we've encountered in working with APIs like a data structure that needs to be serialized into a URL parameter in a certain format.

Suggested swagger modifications:

(Examples from api_descriptions/sendgrid/sendgrid.json)

errorResponses:

This is supposed to be a simplification, making it unnecessary to specify the same errorResponses block over and over again.

• Global error definitions that can be overwritten per api/operation
• specify retry count per error (to automatically retry X times before escalating the error)
• specify where error details can be found (body, header) so this information can be included in error messages

Example:

{
    "apis": [
        "..."
    ],
*   "errorResponses": [
        {
          "code": 400,
          "reason": "Parameter error",
          "details": "body"
        }, 
        {
          "code": 500,
          "retry": 5,
          "reason": "API call was unsuccessful"
        }
    ],
    "basePath": "https://sendgrid.com/api",
    "resourcePath": ""
}

Authentication:

Proposal for an authentication section in the description, including an example for token based authentication.

• specify a global authentication configuration
  • types could be token (with parameters specified), oauth, or others (easily extensible)
• specify per-api if authentication is required, optional, or does not apply (none)

Example:

{
    "apis": [
        {
            "description": "Mail sending", 
*           "authentication": "required",
            "operations": [
                {
                    "httpMethod": "POST", 
                    "nickname": "send email", 
                    "parameters": [
                        "..."
                    ], 
                    "summary": "Send text email to one recipient"
                }, 
            ], 
            "path": "/mail.send.json"
        },
        "..."
    ],
*   "authentication": {
*       "type": "Token",
*       "parameters": [
*           {
*               "allowMultiple": false, 
*               "dataType": "string", 
*               "description": "This is the same credential used for your SMTP settings, and for logging into the website.", 
*               "name": "api_user", 
*               "paramType": "query", 
*               "required": true
*           },
*           {
*               "allowMultiple": false, 
*               "dataType": "string", 
*               "description": "This is the same password to authenticate over SMTP, and for logging into the website.", 
*               "name": "api_key", 
*               "paramType": "query", 
*               "required": false
*           }
*       ],
*   },
    "basePath": "https://sendgrid.com/api",
    "resourcePath": ""
}

model serialization:

This is an extension to models, detailing how they can be serialized when used as a query parameter. See motivation section at the top for more information.

• specify what format a model should be serialized in, if it is supposed to be passed in the query (i.e. as a string)

Example:

{
    "apis": [
        "...",
        {
            "description": "Retrieve, add, modify or delete permissions.",
            "path": "/credentials/{action}.json",
            "authentication": "required",
            "operations": [
                "...",
                {
                    "httpMethod": "POST", 
                    "nickname": "edit credential", 
                    "parameters": [
                        "...",
                        {
                            "allowMultiple": false,
*                           "dataType": "Permision",
                            "description": "New permissions for the user.",
                            "name": "permissions",
*                           "paramType": "query",
                            "required": false
                        }
                    ],
                    "summary": "Modify credentials for your account."
                },
                "..."
            ]
        }
    ],
    "models": {
        "Permission": {
*           "serializable": "json",
            "properties": {
                "email": {
                    "type":"int",
                    "description":"access to SMTP",
                    "allowableValues": {
                        "valueType":"LIST",
                        "values": [0, 1]
                    }
                },
                "api": {
                    "type":"int",
                    "description":"programmatic access",
                    "allowableValues": {
                        "valueType":"LIST",
                        "values": [0, 1]
                    }
                },
                "web": {
                    "type":"int",
                    "description":"web administration",
                    "allowableValues": {
                        "valueType":"LIST",
                        "values": [0, 1]
                    }
                }
            },
            "id":"Permission"
        }
    },
    "basePath": "https://sendgrid.com/api",
    "resourcePath": ""
}