Remote Service API Design

With the longer weekend (Friday Nov 11 is a public holiday in Belgium, to remember the end of WW I) took some time to watch some sessions from the Devoxx conference that has just finished. The talks are already available on Youtube! Great content: Microservices, Reactive, Netty, Kafka messaging, Docker, ... With this conference almost in my backyard, will have to free up some time next year to attend again myself.

One talk immediately drew my attention: "Effective Service API Design" by Elliott Rusty Harold. I know Elliott an XML guru. Remember being at the speaker's table with him at XML DevCon in London back in 2001 where I presented "Understanding SOAP".

Some thinks I picked up:

• "Contract first" >> "Documentation first"
• Start small (MVP Minimum Viable Product, YAGNE You Ain't Gonna Need It)
• Leverage the URL, not everything 
• Prefer idempotency
• Use standards: UTF-8, standard data/date formats, standard decimals with 2 digits 
• Avoid required data elements
• Deprecation policy, how long to keep the old API, 2 year notice is good
• Plan for versioning: easier without schema's but with optional fields
• No assumption about use of client code/library, developers will often not use those 
• If you build client code/library, develop it by hand and do not generate it 
• Authentication and authorization remain a challenge
• Performance!

Although a good talk, would have hoped for some more specific guidelines.

 
•  1:00:41

  Effective Service API Design by Elliotte Rusty Harold

At the start of the presentation, Elliott clearly makes the difference between the local "library API" (e.g. the JDBC API with the java.sql package) and "Remote API" or "Service API". Great definition by the way: a network service (almost always a server) by which programs communicate with a bundle of funcitonality provided by code owned by somone else, running on their computer (not yours).

Thanks to the Devoxx team and Stephan Janssen to publish this great content for free!