User:SFaci-WMF/API Lifecycle Management

Some considerations

edit
  • The intention of this draft is to describe all the steps (and needed tools) that every team must follow to create a new API or update an existing one
  • Every necessary step/task to develop and deploy the software that implements all the endpoints won't be included here because they are not subject to this lifecycle or the API Guidelines
  • Must take into account that all the steps (except the software development) should/could/can be guided or supported by the API Team (and other teams?) and its stewardship could be even shared between this or other team (deployment team?, security team?, performance team?) and the API producer.
  • This is a quite specific proposal with specific steps and tools. Of course, all of them can be replaced by similar ones more appropriate to the current technology stack or event removed if not applicable.
  • Nothing about API Advisory, Adoption or Monitoring is included here yet. This document is just intended to be a minimal starting point to start working on. Although they could also be considered at this moment, they can be added later and, in this way, reduce the initial scope.

API lifecycle

edit

Requirements gathering

edit

Tools: API Team, API asset manager/API Portal, common model

  • Collect and write down new requirements for a partial or full API (API draft)
  • Look up existing APIs that might fit
  • First meeting with the API Team might be scheduled to start giving guidance/support

Design

edit

Tools: API Team, OAS templates, Spectral, common model, Swagger editor, Postman, API Guidelines, Wiremock

  • Focus on API First: You have to design first, at least, what you are going to build. Later, you can iterate through the entire lifecycle to add new endpoints or update the API
  • Create/update, review and validate the definition for the partial or full API
  • Create/update a sandbox API and provide the test collection
  • Add/Update the API to the API asset manager

Development

edit

Tools: OAS definition, swagger-codegen/openapi-generator?

  • Write the code (not supported by the API lifecycle)

Testing

edit

Tools: API Team, Postman + Ajv + Newman

  • Create/update the test collection (+contract testing?)

Documentation

edit

Tools: API Team, API Portal, API Guidelines

  • Add/Update documentation to the API Portal (definition + test collection + best practices + resources + . . .)

Deployment

edit

Tools: API Team, API Gateway

  • Deploy the API in the API Gateway: Can be included something as contract testing in the CI/CD pipeline?

Deprecation

edit

Tools: API Team, API Guidelines, API Portal

  • Follow API Guidelines to see what the deprecation strategy is

Appendices

edit

Tools

edit

More information

edit