Page MenuHomePhabricator

Client Developer downloads machine-readable definition of the API
Open, Needs TriagePublic

Description

"As a Client Developer, I want to download a machine-readable definition of the API, so I can generate tools or documentation from it."

This is somewhat teased out from T236113: API developer creates automated documentation, which is about automated documentation generation. One way to do that is to use a standard API definition language like OpenAPI or RAML to define the API, and then using off-the-shelf or custom text generators to create the documentation from that definition. But it's not the only way.

There are other benefits to having a machine readable definition of the API, though, which make it a separate user story:

  • Automatic building of client-side libraries for the API (although these usually aren't great libraries)
  • Automatic documentation in different formats
  • Integration with IDEs, linters, or other automated development tools

There are a number of languages used for API descriptions. OpenAPI seems to be the main one used right now, but there might be a case to be made for other languages instead of, or in addition to, OpenAPI.

Event Timeline

This is an interesting feature, but I think it deserves to be an epic, there's a lot of work to be done here.

First, to clarify, which API are you talking about it? Core REST API or API Gateway. The former is a subtask of the latter and thus smaller/easier.

For OpenAPI support in Core REST API, I think @apaskulin has some very good notes and tickets that she could add here.

As for gateway OpenAPI, things get more interesting. API Gateway collects various APIs implemented in various backends into the same structure, ideally hiding the implementation of the specific endpoint. It will also probably mangle some of the parameters/paths to make the user-facing API more consistent. Thus, the spec of the API provided by the gateway has to be collected from various backends, merged and mangled the same way gateway is mangling the paths. In RESTBase we have chosen the easy path and just copy-pasted the specs from individual services when exposing them, but with experience we've come to an understanding that it was probably a mistake - copying the specs is too much overhead and is doomed to diverge.

Thus, to support OpenAPI in the gateway, we would probably need to create a spec service. A service would be configured with exposed endpoints and pointers to where to download the specs from individual services and have the ability to merge/mangle them. Additionally, we could annotate the paths with various tags and have it support json-path-like routing for fetching segments of the spec. That would allow us to generate executable snippets/docs for parts of the API, potentially embed them on the API Portal wiki. This has the potential to be very very cool.

If we ever deploy RDS for api-gateway envoy, the spec service could fetch it's config from RDS as well.