Necessity to have a RESTful API about docs-api HOT 8 OPEN

I know we need to be more RESTful. No doubt about that. What's in place now is basically minimum viable product to get people started. All of these comments are great. I'll start a v1.1 API layout that we can all add to. OpenAPI is laid out with YAML if I remember correctly. I think Postman has support for it.

Having a v1.1 that conforms to OpenAPI, and then leaving the current v1.0 active seems like a good balance for those that just want quick hits without full REST, and more robust platform folks.

from docs-api.

@daveajones Is the server-side API code available in another repo?

from docs-api.

I agree that establishing RESTful conventions early on is important - proper use of HTTP verbs is key. I'm a fan of structuring complex queries against OData v4 protocol (v3 support is probably advisable also), rather than having a custom convention for query structure. Many clients will consume OData v4 readily to provide filterable grids, sort, count, pagination, etc. Complex queries can optionally be passed via the HTTP body content as well, as to avoid busting the URI length for GET requests or running into encoding problems.

Make the API self-documenting, featuring an Open API 3.0 (Swagger) metadata endpoint to facilitate automatic client code generation. A web-based, interactive API browser is always a nice touch when trying to attract new developers.

The URI needs to be a short as possible while still being easily legible - for example, "api" is already in the domain, so I believe that could be removed from the stub.

The API version could either an optional query parameter or HTTP header (defaulting to the latest). I imagine the write-end of this API could face some significant breaking changes, especially early on, however, the read-end should strive to be very forward compatible - accessing beta features or pinning code to a specific release becomes a consumer option, but not a requirement.

Combined with making use of pluralization in the semantics, the API can be pretty intuitive:

GET api.podcastindex.org/podcasts
GET api.podcastindex.org/podcast/1/episodes?ver='0.1.0.254-beta'
GET api.podcastindex.org/podcast/3/episode/1

...and to scratch the query itch with something more complex, collections can be handled via OData:

GET api.podcastindex.org/podcasts?$filter=contains(name, 'Some Agenda')&$expand=episodes($filter=lastUpdateTime gt '2020-01-01')

Following on with RESTful conventions, we can really expand into quality of life improvements for developers, like enriching the response body with navigational properties to downstream entity queries - e.g. HATEOAS (Hypermedia as the Engine of Application State) - this could really help simplify client SDK development, because you can recurse through the entity definition even if the link refs have to change later on.

from docs-api.

from docs-api.

@daveajones Is the server-side API code available in another repo?

Not yet. It's a custom framework, so let me figure out the best way to split it up and I'll put something up.

from docs-api.

@daveajones +1 for Open API spec. I've found this tool really helpful for building out OpenAPI specs btw: https://stoplight.io/

from docs-api.

This looks like an interesting tool to use that could take the doctrine code comments and generate the OpenAPI/Swagger json file from our own code documentation: http://zircote.github.io/swagger-php/.

from docs-api.

That is an interesting tool. I need to start testing that. Thank you for passing along.

from docs-api.