search

AusDTO / apiguide

API Design Guide
http://apiguide.readthedocs.org/
Other
43 stars 32 forks source link

build_and_publish/advertise.rst is an unresolved solution #24

Closed monkeypants closed 4 years ago

monkeypants commented 9 years ago

advertise.rst suggests emailing the DTO to publish/advertise APIs.

That's not enough, there is no system in place yet. What system should there be? Do we want something more than a friendly note (RAML files? what about SLA info?).

Ideally we should have an API for registering/discovering APIs! That's also human browsable/searchable. We need to figure out what and how much to do for BETA.

markmuir87 commented 9 years ago

I think a simple web form would suffice initially (and be fairly frictionless). An API to register APIs might add unnecessary complexity, and should only be needed if APIs were being published in such volume that automation is required. We could build a multifaceted search based on form inputs (e.g. department, purpose, format, protocol etc), and maybe do a little bit of manual curation where needed.

Personally I'm leaning away from prescribing 'one documentation format to rule them all' (e.g. RAML, swagger etc.), as this will never be a one size fits all situation. Although there's some appeal to uniformity, we don't want to discourage agencies/departments from publishing simpler and smaller APIs because the required documentation format makes it not worth the effort.

Also, there's the possibility that members of the public will discover 'unintentionally published' government APIs, so we should ensure it's quick and easy for them to submit to the register.

Perhaps a compromise would be to suggest preferred formats (RAML, Swagger, ReadTheDocs), and provide infrastructure and guidance that API publishers can use?

monkeypants commented 9 years ago

+1 on the "public discovery" use case. That's a great idea!

monkeypants commented 9 years ago

The reason I mention RAML and SLA is because I see this maybe converging on an API gateway solution at some stage. An API gateway would provide common platform benefits such as consistent instrumentation, one-stop-shop for integrators, standardised configuration and change management policies (SLA "contracts"), etc.

But that's a significant chunk of infrastructure work. Providing an "API catalogue" site/API would be potentially useful on it's own, without any kind of Gateway features. It just doesn't exist (yet).

Interesting to consider overlap with #9. If we formally mark-up conformance criteria using custom sphinx directives, then a custom sphinx-builder could generate an configuration of a self-assessment microservice/app. It's not much of a stretch to imagine such an app supporting the following use-cases:

The whole thing could be totally generic - for example, the sphinx-builder could generate a complete django app using nothing more than some (over-ridable) templates and the appropriate admonitions in the documentation. So it wouldn't be limited to apiguide (versions), it could be used for any documented thing with conformance criteria. Neat little project...

Question is; how to model conformance. Is it sufficient to have boolean conformance (complies or does not comply) with fixed classes of conformance (MUST, SHOULD, MUSTNOT, SHOULDNOT)? Do we need to support "(>=n, <=n, n) OF (listed items)" type criteria? Do we need to have "comments" for some but not all criteria?