OpenAPI Spec for new API

Stefan4472 commented 2 years ago

In the "API First" mentality, create an OpenAPI Specification before implementing anything. Get feedback from one or two experienced reviewers.

Stefan4472 commented 1 year ago

See https://github.com/Stefan4472/Stefans-Blog/blob/master/flaskr/api.yaml

Open questions:

Does it follow best practices for API design (e.g., are the responses as expected, are there any missing error codes)?
What about the design of the publishing and featuring endpoints. Is POST and DEL to /published and /featured endpoints good REST design?
Does it make sense to use the /posts/<postId>/content endpoint to access/modify the Markdown content of a post?
Does the /files POST endpoint follow best practices?

Stefan4472 commented 1 year ago

TODO: see if https://opensource.zalando.com/restful-api-guidelines/ has any tips that would be relevant here

Stefan4472 commented 1 year ago

The spec is not perfect, and will certainly have a few more bug fixes and updates in the future. However, I think it's good enough to start implementing.

Stefan4472 / Stefans-Blog

OpenAPI Spec for new API #68