63.0b Concepts - terrytaylorbonn/auxdrone GitHub Wiki

63.0b Concepts 24.0924

This page is a WIP (work in progress). See also ___concepts.docx (outdated) on Gdrive.

This page decribes the main API doc concepts as I understand them (diagrams are my original)

  • 1 API doc types
  • 2 API doc workflows

1 API doc types

For now just quick "napkin" drawings (created 24.0924). Will redo later.

63.1 API only

An app contains the code (Fast API, etc) for generating the API (which provides access to app functionality).

image

63.2a API + (built-in) doc

The Swagger file is generated from the

  • API code (inside the app (not shown in this diagram xxxxxxx))
  • Comments inside the code (API description, etc)

image

63.2b Doc only

The Swagger docs can be created

  • manually (diagram below)
  • generated from an app like Sphinx (NOT SHOWN IN DIAGRAM XXXXXXXXX)

image

63.3 GraphQL

GraphQL basically does the following (my understanding; if I am correct, then I dont understand why I never seen such a straightforward description anywhere, especially from official GraphQL docs):

  • The query tool is used to create a query that specfies a tree of only the objects needed.
  • Query is sent to the Apollo server.
  • Apollo server executes the REST commands required to get all the required objects.
  • Apollo "distills" the content to send back to the query tool

image

[63.4 Test (Postman)]

Postman is used to test the API endpoints. Postman is like a browser that allows you to control things "under the hood". Postman can

  • Send URL requests like the browser
  • View and control request/response parameters (like browser F10 dev tools)
  • Main a history of commands (like browser history) and request/response details

image

63.5 Doc only deploy

Swagger docs can be published by sending to a host server that publishes

  • Without app server (for example: Gitbook)
  • With app server (such as NPM) (for example: Railway, AWS)

image

63.6 API deploy (maybe + built-in doc)

Swagger docs can also be published witin the app deployed on an app server.

image

2 API doc workflows

Pie in the sky workflows

  • Design APIs first with Swagger before coding (no one does this).

Ideal workflows

  • Create (basic) APIs.
  • Create API definitions / schemas from code.
  • Publish API docs (hosting sites, Railway, AWS, Gitbook, Heroku, etc).

Real-world API doc workflows

The following has been the typical workflow for my recent projects:

  1. Collect the existing API docs (what little existed).
  2. Learn the API hands on (using Postman/Swagger) with minimal assistance.
  3. Make my work available internally (usually via simple a tool like a Github wiki).
  4. Create hands-on quick start / getting started docs (with examples, examples, examples).
  5. Create a conceptual explanation of the big picture.
  6. Create a sanitized/obfuscated version of API (generate from code or (my preference) edit the swagger file directly).
  7. Publish the API (first internally, then externally) in something like Gitbook, a React app, etc.

The API docs I created provided details about the options, workflows, and prerequisites for endpoints. Documenting special cases that often are difficult to specify with just a swagger file.

All projects were successful. However

  • Published output was only made available to customers (not public) or the product failed.
  • My working docs were the confidential property of the client.
  • I did not record the details of what I did. That last day on the project always came much quicker than I expected.