Customer Facing API Docs

We need to push the official API spec down to the developers who are working on the code. Catapult Documentation is currently at risk of becoming out of sync with the API behavior. Any documentation changes have to be funneled from the development team to the dev x team.

The state of things

Iris (dashboard, numbers API) currently documented in its entirety using a custom pre-processed RAML0.8
- Major reason for pre-processed is to keep internal APIS hidden from external users example: GET /accounts
Iris has about ~600 endpoint/method combinations documented in RAML0.8
Catapult (Application Platform, voice & messaging APIs) has used swagger (open api spec) minimally to document v2 APIs, but the core API doesn't have an official API Spec.
Internal APIs throughout the back office have been using Swagger(OAS) to document their APIs and provide minimal documentation.

Where we want to go

We want to default on a standard for our CUSTOMER FACING API docs. Keeping everything in a standard format lets us reuse the tool-chain for any updated/new CUSTOMER FACING APIs

Desired process

Dev X team reviews each new PR containing documentation updates. The prose should be kept as part of the API Spec.
Development provides official spec each deploy
Dev X team pulls official spec from URL provided my development team
Official spec is run through generator(s) to create documentation website

Dev X work

Create prose checklist, templates, and training
Review changes to prose made by development
Write initial prose for new/updated endpoints/methods
Develop tool-chain for turning official spec to Dev site

Development work

Maintain official API Spec
Update endpoints/methods and prose when changes are made
Incorporate Dev X team on prose/docs updates
Provide official spec each deploy

My Suggestion

But first some forward -> Swagger(OAS) is the current market winner, and if we had 0 spec finished it would be the obvious choice. However, having Iris completely documented using RAML is the leading factor in my suggestion

Task	Time Dev X
Convert Iris docs from RAML0.8 to 1.x. RAML1.x adds support for annotations which allow a custom property that can contain scope for us	2 weeks
Convert Iris docs from RAML0.8 to Swagger(OAS)	4 weeks
Clean up Iris docs and rework some of the descriptions/examples (HTML -> Markdown where applicable)	2 weeks
Document Catapult with RAML	4 weeks
Write RAML to Bandwidth Docs Conversion	4 weeks

Demo rework from RAML0.8 to RAML1.0 to Swagger

0.8

!fileScope external

description: Retrieves the total quantity of phone numbers from the specified order.

!scope external
get:
    description: Retrieves the total quantity of phone numbers from the specified order.
    responses:
        200:
            body:
                application/xml:
                    example: |
                        <TelephoneDetailsReports>
                            <TelephoneDetailsReport>
                                <NPA-NXX>888424</NPA-NXX>
                                <Count>1</Count>
                            </TelephoneDetailsReport>
                        </TelephoneDetailsReports>

1.0

description: Retrieves the total quantity of phone numbers from the specified order.

get:
    (scope): external
    description: Retrieves the total quantity of phone numbers from the specified order.
    responses:
        200:
            body:
                application/xml:
                    example: |
                        <TelephoneDetailsReports>
                            <TelephoneDetailsReport>
                                <NPA-NXX>888424</NPA-NXX>
                                <Count>1</Count>
                            </TelephoneDetailsReport>
                        </TelephoneDetailsReports>

Swagger

Note that the return type needs to be specified on it's own doc as a /totals request should return a type of TelephoneDetailsReports

    "/accounts/{accountId}/orders/{orderid}/totals": {
      "parameters": [
        {
          "name": "accountId",
          "in": "path",
          "required": true,
          "type": "string"
        },
        {
          "name": "orderid",
          "in": "path",
          "required": true,
          "type": "string"
        }
      ],
      "get": {
        "description": "Retrieves the total quantity of phone numbers from the specified order.",
        "produces": [
          "application/xml"
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "x-annotation-scope": "external"
      }
    }

Why RAML

Iris is already done (ish)
Once we provide a 100% valid RAML 1.0 document, there are tools that convert RAML to Swagger and back again. Nothing appears to be lost in translation, but from my research it's not as good as having native swagger/raml.
RAML provides much more advanced !include format than swagger

Clean up

Things like phone numbers, zip codes, area codes, etc.. are processed now as strings. We should define these as custom types representing the validation they're sent through in the code.
Some tables include custom padding/code types etc... that should be stripped out and handled at a higher level

What we need from Development

Agreement that whatever we choose (RAML/Swagger) is the OFFICIAL technology for customer facing APIs. Ideally, any API at Bandwidth should be documented with the final decision, but the conversion tools work well enough for non-customer facing docs
Continued support for final API spec as the APIs grow and change.

dtolb/docs_v3.md