Jump to content

User:SFaci-WMF/API Lifecycle Management

From Meta, a Wikimedia project coordination wiki

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]