Last week, I attended the API Strategy Conference in New York City, where a diverse group of techies got together to talk about the future of APIs for developers, service providers, and big enterprise.
It was a very open discussion about the way both computers and devices talk to each other over both public and private networks. 3Scale and API Evangelist @kinlane organized the event, and by all measures, it was a great success. The mood was open and honest, and a ton of great discussion happened during the talks, in the hallways, and of course, the bars.
While my talk was about Swagger, I was able to attend a whole bunch of sessions and have conversations with some very insightful people. I’d like to share some of the major themes I observed over those two days (I’m skipping the obvious ones, like “everybody wants APIs”).
Delight your Clients. Who are they, again?
While the immediate client is the developer, the ultimate client is the end user. Your APIs need to satisfy both, and that’s not always in-line with the “service-oriented” thinking of many back-end engineers. The use cases should drive the solution, and you shouldn’t cut corners.
The API versioning problem
Versioning APIs is an unsolved problem. It’s hard since signatures, payloads, etc. are both difficult to detect and provide as it typically means running more servers than you may want to. api500.com has a good list of how this is done, but let’s revisit that topic in a bit.
Developer-friendly Stripe has a very cool solution to this – an API version is associated with each integration. That allows their forward proxy (assuming that’s what they use) to route requests to the right place. Upgrading at your own pace is an excellent way to keep developers happy. Really.
API Discovery is fragmented and needs improvement
How do you find APIs? How good are they? Would you trust them in the middle of your application workflow? We need more than just a directory of APIs – we need both developer feedback and metadata about the API. How many people integrate with it? What’s the uptime? How are the drivers? How often does the signature change?
Folks like Singly and Webshell are building abstraction and unification layers to 3rd-party APIs. That certainly makes discovery easier, since the underlying services need integration and are therefore known. New services, however, need to be found, and the whole issue of developer feedback needs to be integrated.
Not all APIs are for fetching photos or tweets about cats
APIs can be simple. Zero workflow required (once authenticated), even if there’s complex processing happening behind the curtain. But that’s not always the case, and workflows are required.
This entails passing values from one API call to another. Often there are branches in logic, depending on what happened. This makes the complexity of the API documentation snowball. Who has nailed this? From the discussions, apparently nobody.
The enterprise is coming! And they are skeptical about services in their workflow
Even big companies with tons of resources need to open up their services to stay both competitive and nimble. Developing for mobile devices has driven this need very quickly – they have, though, some additional challenges.
Some are public companies. Many have gigantic traffic requirements. They might have scary SLAs and deployment requirements. The thought of sticking a multi-tenant, cloud-based service run by five smart guys from a coffee shop in San Francisco being put smack in the middle of their workflow is often a non-starter. They want control of the systems, backup systems, and a big red telephone for when something goes wrong.
Solving small shops (developers) and the enterprise is an almost intractable problem for most small companies. It’s very important to know who your target market is.
REST is not a silver bullet
There was a deafening silence in the second day keynote when Daniel Jacobson said that Netflix is moving away from REST. Whaaaa?
Backed by usage data (and lots of it), investigation, and solid engineering, Daniel made a very compelling argument against REST as a one-size-fits-all solution for your connectivity needs. The often-complex workflow required by clients can be accomplished in a single request to their API, which returns presentation data, not raw data.
They call it an “Experience API”, and there may be discrete endpoints for each device type. This gives server developers more freedom to change code without risking everything and makes a more streamlined request/response cycle to get presentation data. Remember in the first point, the end user is the ultimate client. So if you can make things faster and give a good or better experience, you are winning.
How about that API versioning issue?
Let’s talk about API versioning. It’s a big problem as I covered in my presentation during the API tools track. What happens when you change the signature of the API? How will developers know, other than their app breaking? Maybe you add a new API – how do your developers find out about it? Twitter? Diffing your documentation?
Turns out that what most people do is what was described by api500.com, and I have to say, it’s almost pure luck if you find out about an API change before it’s too late. Do you personally keep up with your twitter feeds? Never missed a message from @twitterapi? Read those developer emails?
Turns out Swagger can help with this problem. When you describe your API through Swagger, you can easily scan the API description and detect changes. Then it’s up to you to act on them. Here are some examples.
1. Model changes. Let’s say you have an API like the Swagger Petstore sample. This API describes a Pet model through the Swagger JSON:
Here, the description field is not required. Say that changes, and you require it now – and if not present, you start returning 400 response codes and break all your consumers over that one change!
Detecting this change is trivial, by scanning the API Declaration for this particular API. It’s just JSON, and diffing the two is easy.
2. New functionality. Say you add a new operation to your API – how does the world find out about it? Again, change detection is quite simple once accurate Swagger descriptions are produced.
To keep people sane, it’s important to use computers wherever possible to do mundane tasks. While I love the Twitter API Docs, I really don’t care to read them every hour looking for changes.
And did you know that decoupled documentation systems (like Twitter’s) are typically updated after the API is changed? It’s true, software development is much faster than documentation. So what if we had an API directory which not only allowed user feedback on uptime, drivers, etc., but also could detect changes in the APIs it lists, and report back to the users who follow them? All you need is an interface to describe the APIs themselves – the rest is easy.