larlet-fr-david/david/blog/2016/specifications-apis/index.md

title: Specifications and APIs
slug: specifications-apis
date: 2016-09-15
lang: en
chapo: To me an API is a discussion between involved parties.

> One does simply not generate specifications from code.
>
> <cite>[Darrell Miller](http://www.bizcoder.com/), [OpenAPI 3.0 - The evolution of a success story](http://www.meetup.com/fr-FR/api-montreal/events/233496023/?eventId=233496023) (I cannot remember the exact sentence so I meme-ize it, sorry)</cite>

[OpenAPI](https://openapis.org/) 3.0 is the new rebranded, improved and community-driven [Swagger](http://swagger.io/) [specification](https://github.com/OAI/OpenAPI-Specification), a way to interface an HTTP API. It was interesting to get an overview of what’s new and currently discussed on the specification itself but a question from the audience had all my attention because I felt highly concerned with the work we’re doing at [data.gouv.fr](https://www.data.gouv.fr/) using Swagger for the API. The case described — generating the Swa^WOpenAPI file directly from (Python) code — is exactly our process to [document the API](https://www.data.gouv.fr/fr/apidoc/) and even consume it on the JS side.

That was the moment Darrell made a break and explained that you have to *take care* of your specification/contract; it has to be hand-written, not generated. That’s what killed SOAP with the complexity added by automated generators (and consumers). That made me think about the ascendant relation of an API with the server taking all responsibilities and clients which are accepting constraints. It doesn’t have to be that way. When you write the documentation of your API you take the time to think about the necessity of a given resource or verb. You can define an API based on actual needs from clients. You take the time to check your analytics to deprecate unused resources and so on.

**To me an API is a discussion between involved parties.** They should share responsibilities and constraints over time like in any relation. There is no such thing as engraved endpoints and we should be better at versioning these relations to lead towards the best paths for both sides. We can avoid performing [many requests](http://githubengineering.com/the-github-graphql-api/) ([cache](/david/cache/d9457ea0fba660a5011e8671f44f212c/)) for a given action, this is adaptation to a given context but it has to be discussed and constantly challenged. *The other way around is something as generalist and unoptimized as GraphQL.* Everybody is enthusiast about that shiny-new-Facebook technology because they lack communication skills and they hope that it will avoid that necessary conversation between developers on both ends. It will just add an extra layer of complexity.

That being said, I’ve been a long-time advocate of REST/hypermedia which is another way to avoid that discussion too. Today I’m more inclined to focus on a few pertinent scenarios. Maybe is it related to a change in my personality with more empathy for my peers? :-)

> You don’t pay engineers to write code, you pay them to understand subtleties and edges of the problem. The code is incidental.
>
> <cite>Ted Dziuba</cite>