I move to define PyPA and Warehouse HTTP APIs with OpenAPI definitions.
> OPENAPI SPECIFICATION
> The OpenAPI specification (formerly known as the Swagger Specification) is a powerful definition format to describe RESTful APIs. The specification creates a RESTful interface for easily developing and consuming an API by effectively mapping all the resources and operations associated with it. It’s easy-to-learn, language agnostic, and both human and machine readable.
> The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
> An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
- It's possible to generate WAF (Web Application Firewall) rules from a Swagger/OpenAPI definition.
- There's an online editor.
- There are many integrations for various languages and frameworks.
An OpenAPI spec/schema can be written by hand as YAML or JSON, autogenerated from e.g. decorators or docstrings or framework integration.
Here's the online editor with validation:
> Convenient tools for using Swagger to define and validate your interfaces in a Pyramid webapp.
Request/response validation do have overhead and may be best done in a WAF, but there's no reason not to serve e.g. /swagger.json or /swagger.yml with the API spec for this app.
OTOH, DevPi and Pulp Project support the v1 upload API.
An initial OpenAPI schema definition document for just the v1 upload API e.g. path, request, and response shouldn't take much time at all.
On Wednesday, May 9, 2018, Nick Coghlan <email@example.com> wrote: