On API Design

Last week I gave an initial presentation for our API Design Guild at work and I presented a variety of API Design scenarios using not only REST API examples but older ones such as C libraries, microcontroller libraries, and binary protocols. I think I just about lost everyone when I put up a picture of a microwave panel! My point was that the API is truly the Application Programming Interface. This is how we communicate with something and get it to do what we want. I think a lot of the API articles we have seen the past five years are all about the new web world where Javascript is king and JSON flows freely. But the API design is really about how the application acts when spoken to and has little to do with its surrounding, language, or framework used to build it. I watched this thirty minute presentation on API Design today by Mike Amundsen and I think it might clear up some of my inability to explain my thoughts on API Design that I presented a couple of weeks ago. Basically it is the concept of separating design from the implementation details.

Check it out here:
API Design Methodology

The seven point procedure that Mike Amundsen talks about in his presentation and starts off with ‘What is a design methodology?’

1. List the Semantic Descriptors
2. Draw a State Diagram
3. Reconcile Names
4. Choose a Media Type
5. Write a Profile
6. Implementation
7. Publication

What I find fun about API Design is the fact that you are creating a new entity and deciding how it interacts with the world. The language, framework, internal connectivity, and persistence layers are totally irrelevant at this point and it is best if you can somehow completely ignore them.

Good luck on your next API Design!

Thanks for listening,
David Nordstedt