← Developer Relations (DevRel)

API Docs Cleanup Process

Why we need a process

We need to have solid documentation for our APIs on JackHenry.Dev. Think of Stripe or Twilio. If it’s documented on their developer site, then developers can rest assured that it’s accurate.

The DevRel team works with various GitHub Repos, but these are the most relevant for JackHenry.Dev:

Sources:

API Gateway:

JackHenry.Dev (Banno developer docs)

The purpose of this page is to document the steps that we must take to cleanup the API docs so they can be published on JackHenry.Dev.

Note: You’ll want to be familiar with some of the tools we use on the DevRel team.

The Process

The steps in this process can be done as individual PRs in their respective repos.

Alternatively, you could do these steps as individual commits (preferably using conventional commits) to make reviewing easy within a single PR in a repo.

Sources

1) Verify the Swagger/OpenAPI spec file in the Swagger Editor does not contain any validation errors

  • When you dive into a specific set of API endpoints (e.g. User / Accounts), the rendered docs have a link up near the top of the page which opens up the Swagger/OpenAPI spec file.
  • Save the file (or copy and paste the contents) and open in the Swagger Editor.
    • Don’t change the format or version in this step.
  • If there are no validation errors, then you’re done with this step.
  • Else fix the validation errors and open a PR in the repo. Example PR

2) Convert Swagger/OpenAPI spec file from version 2.0 to 3.0

3) Run docs-splinter against Swagger/OpenAPI examples vs real API responses

  • When looking at a specific API endpoint (e.g. GET ​/users​/{userId}​/accounts), you’ll see an Example Value which contains a sample JSON response.
    • Copy and paste this JSON text into a file with the .json extension. This is your Documented response.
  • Make an actual API call and get the JSON response.
    • Save this JSON response into a file with the .json extension. This is your API response.
  • Use the Docs Splinter tool to determine if the Documented response matches the API response.
    • Fix up the following, where necessary:
      • Documented properties that are missing in the API response.
      • API response properties that aren’t documented.
      • Mismatched data types.
    • This step may require working with one of the data services teams (domain owners).
  • Open up a PR in the repo.

4) Update API References and Scopes

  • For each .yaml Swagger file, ensure that the correct attributes have been set to enable the interactive API reference:
    • servers (YAML example)[https://github.com/Banno/open-api-docs/blob/master/src/docs/consumer-api/api%20reference/v0/accounts/details/accounts.swagger.yaml#L5-L15]
    • The securitySchemes element within the components element:
components:
  securitySchemes:
    OpenID_Connect:
      type: openIdConnect
      description: OpenID Connect - Discovery endpoint will be institution specific
      openIdConnectUrl: >-
        https://digital.garden-fi.com/a/consumer/api/v0/oidc/.well-known/openid-configuration
  • For each endpoint defined within the .yaml file, remove explicit versioning from URL (eg. /v0/institutions/{institutionId} to /institutions/{institutionId})
  • For each endpoint defined within the .yaml file, ensure that the correct security scopes have been defined scopes reference

API Gateway

1) Review the Adding a service to node-api-gateway docs

2) Update or Create Service Definition file

  • If the Service Definition file exists in the correct folder (in this case, v0), then update the routes.
  • Else the Service Definition file doesn’t exist, then you’ll have to create the file in the v0 folder and fill in the details of the service definition and the routes. Example PR
    • Tip: You may be able to find a file in the unversioned folder that will give you a head start on creating the file in the v0 folder.

JackHenry.Dev

Example PR – see Summary and commits

1) Create folder structure in open-api-docs repo

(If necessary…which means there isn’t already an existing folder structure).

  • Create named subfolder in correct version subfolder (e.g. v0) of the api reference folder in the open-api-docs repo. Example PR
    • e.g. If this is for Institutions/Details, create an /institutions folder with a /details subfolder.
      • Also create an index.md file with a frontmatter title that includes the name of this API section e.g. Institutions
  • Add ’explanation’ information on what this data entity/object is to the index.md file. At a minimum, needs to include a link to the API Reference for more details. Example PR

The finished structure should look something like this (using the Institutions/Details example from the above steps), with two different .md files and one .yaml file:

institutions/
    - index.md
    - details/
        - index.md
        - details.swagger.yaml
  • Commit the above as a commit with message on what was done.

2) Get API spec source files (.md and .yaml) from the source repo

  • Get the source files from the source repo and copy them over to the subfolder created
    • e.g. for Institutions/Details, that would be within /institutions/details
  • Note the commit hash versions in the source repo, as we add this as part of the commit in the new repo so it’s easy for us to track back to the source repo. Example PR
  • Commit the above as a commit with message on what was done.

3) Modify info from the source files that have been copied over

There is some information that is displayed in the source repo that we simply don’t display or display differently on JackHenry.Dev. - Remove any API endpoints that were aren’t going to expose/support as part of the Open API from the .yaml file. - Remove any version info from API paths in the .yaml file. - Remove changelog information from the .md file. - Remove links to internal-only content from the .md file. - Remove extraneous info/sections from .md file. - (This is more of a judgment call on on what is considered “extraneous” to a JackHenry.Dev reader.)

4) Build and run the above changes in Gatsby

  • Make sure that the above things render and link properly locally.

5) Create PR to open-api-docs repo

  • With all the work done above, this should be the easiest step. 😄
  • Once the PR is approved and merged, the auto-deployment process will publish the docs on JackHenry.Dev.
  • Make sure that once everything is published that things render and link properly on the live site. Time for beverages. ☕️🥤🍵