This is the Joel Spolsky article with the good old Shlemiel the painter’s algorithm: Back to Basics.
I’m reading RESTful Web Services Cookbook and on page 17 the author gives this example:
# Request POST /user/smith HTTP/1.1 Host: www.example.org Content-Type: application/xml;charset=UTF-8 Slug: Home Address <address><street>1, Main Street</street><city>Some City</city></address> # Response HTTP/1.1 201 Created Location: http://www.example.org/user/smith/address/home_address ...
There are two problems with this: the first is that “POST /user/smith” has the semantics “register address”, so it would be better if that was clear; the second is that some of the input to the business process is in the XML payload, while some of it is in the HTTP headers (viz Slug). It would be better if all the input was in the payload.
So how would I design this service?
# Request POST /api/v1/processor HTTP/1.1 Host: www.example.org Content-Type: application/x-www-form-urlencoded action=register_address&user=smith&street=Main+Street&city=Some+City&type=home_address # Response HTTP/1.1 303 See Other Location: http://www.example.org/user/smith#home_address
Actually in my designs the /api/v1/processor could be anything, including /user/smith, because the business process is indicated in the request ‘action’ with is submitted with POST. Just like God intended. Idempotency, optimistic concurrency control, authentication, authorisation, auditing, version control, all that good stuff implemented with business logic via business process for ‘register_address’.
Today I discovered: Documenting APIs: A guide for technical writers and engineers.
A well designed website: Nielsen Norman Group… :)
From here some interesting stats:
- 6 million PHP programmers
- According to Linkedin, Facebook currently employs approximately 8850 software developers.
- At Amazon, there are around 36,000 developers writing code.
- Apple employs around 20 million developers, and together they have made about $100 billion in revenues.
- As of now, Netflix employs only 80 software engineers, who build 50 applications.
- According to the official Google employee report, 27,169 software engineers work at Google (i.e. research & development).
Today I discovered wikiscript: Open Data Scripts for Wikipedia – Turn Free-Style (or Semi-Structured) Text into Structured Data.
This is great: Formally Modeling Database Migrations. I need more formal methods in my life.
Some tools for API documentation: Say Goodbye to Manual Documentation with these 6 tools.
I came across this today and thought it was a good example of a service availability reporting system: www.fastmailstatus.com.