3 min

API-first-development design

Simple enough. Another project derivative idea based upon Junco code. No HTML Template usage. The server code only receives and returns JSON via REST API calls. The client code can do the formatting in any manner that it wants. Maybe it's another server app that is acting like a client, such as a cron script. The server code can be created in different programming languages if necessary, and all of their communication is through JSON-REST API calls.

( Update: - In November and December 2013, I created a new Web app called Kinglet that powers http://Soupmode.com which is a simple, Web-based private messaging app that acts like a mini message board or microblog app. A user can message one or more other users. The server code is API-driven, using REST and JSON. )

A lot of "firsts" for design and development:

  1. API first
  2. testing first
  3. mobile first

If doing API first development, then the mobile first thought is relegated to another app or service. Separation.

Links culled from below:

Hacker News top comment:

In the past 6 months, at the urging of my friend Dave (sup!), who suggested this style of development, it's all I've done, even for small personal projects. I sort of take it further, eschewing frameworks somewhat, relying on libraries around actual "Business Logic" to deliver stuff as needed to outside clients.

It's been an eye opener. Sometimes it requires a little more upfront thought, but I end up with a much more maintainable project at the end of it. TDD is your new best friend if you go down this road, and the best part is: it's easier to do test driven development when things are nicely separated like this!

It's basically SRP writ large, and something tells me it's another one of those "ideas" that the grey-beards learned a long time ago that we are only re-learning now. Although REST does kick the crap out of SOAP...

A progressive enhancement and search engine index idea would be for the client-side JavaScript code, in a Web browser, to send additional information in the REST request. If this additional info is not available to the server-side code, then maybe the server code returns a bare, minimal HTML markup instead of JSON. So a template system would still be needed on the server.

Another HN comment:

Our public API is a front end for our other services with auth added on and better guarantees against breaking. We don't depend on it directly for anything public facing and I wouldn't suggest anyone completely rely the same API they offer partners/openly to avoid getting into a tough spot with managing changes.


Are there some go to standards for API design that are followed?

I use the following sources as standards:

- Vinay Sahni's Best Practices for Designing a Pragmatic RESTful API: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

- HN discussion on Vinay's post: https://news.ycombinator.com/item?id=5819231

- Twitter's Error Codes & Responses: https://dev.twitter.com/docs/error-codes-responses

If I can throw my own in: http://john-sheehan.com/blog/dont-build-the-best-rest-api-build-the-best-http-api



A new site was just launched to help with this: apicommons.org
My general advice is if it's internal, build what feels right to your team. If it's external, research the APIs you like or are popular (Twilio, Stripe, etc.) and don't be clever.



  • plural nouns for everything.
  • a post request, creates
  • a get request, reads
  • use same noun for both create and read. the request type determines the action type.
  • do not use root url. use either:
  • http://api.soupmode.com (related to kinglet though)
  • http://kinglet.soupmode.com/api

Top ones to view










#programming - #design - #javascript - #json - #rest - #api - #blog_jr

By JR - 695 words
created: - updated:
source - versions - backlinks

Related articles
Custom Toledo-area weather Web site - Mar 03, 2014
Draftin.com WebHook URL info - Aug 09, 2013
Short list of REST API info - Jan 13, 2017
Reuters' former Next Web system - Sep 19, 2013
July 2016 ToDo - Implement Micropub spec in JavaScript editor - Jul 14, 2016
more >>

short url

A     A     A     A     A

© 2013-2017 JotHut - Online notebook

current date: Jun 14, 2024 - 4:44 a.m. EDT