• Read
• Top ones to view

API-first-development design

• November 2013 Pop.co blog post titled Why we chose API-first development.
• Related Hacker News thread

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:

• http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• https://dev.twitter.com/docs/error-codes-responses
• http://john-sheehan.com/blog/dont-build-the-best-rest-api-build-the-best-http-api
• http://dev.billysbilling.com/blog/How-to-make-your-API-better-than-the-REST
• https://github.com/WhiteHouse/api-standards
• https://draftin.com/documents/54643?token=Qq1PuS1fL8Zr9yWDSefoeUMQCfp3yr1s6g_7ShYKops
• http://micheltriana.com/2013/09/27/http-status-codes-in-rest-web-api/
• http://micheltriana.com/2013/10/07/uri-design-rest-web-api/
• http://micheltriana.com/2013/09/30/http-verbs-in-a-rest-web-api/
• http://developers.box.com/get-started/
• https://stripe.com/docs/api#intro

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.

More:

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

http://jsonapi.org

http://dev.billysbilling.com/blog/How-to-make-your-API-better-than-the-REST

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.

http://pages.apigee.com/web-api-design-ebook.html

Read

• 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

• https://github.com/WhiteHouse/api-standards
• http://micheltriana.com/2013/10/07/uri-design-rest-web-api/
• http://micheltriana.com/2013/09/27/http-status-codes-in-rest-web-api/
• http://micheltriana.com/2013/09/30/http-verbs-in-a-rest-web-api/
• video - http://blog.parse.com/2013/10/02/parse-developer-day-video-series-how-to-design-great-apis/
• http://jothut.com/cgi-bin/junco.pl/blogpost/5224/19Sep2013/Reuters-former-Next-Web-system
• http://jothut.com/cgi-bin/junco.pl/blogpost/1416/Draftincom-WebHook-URL-info
• http://www.perl.com/pub/2012/12/consuming-restful-services-with-perl.html
• http://developers.box.com/get-started/
• http://processwire.com/api/
  • http://cheatsheet.processwire.com/
• http://jothut.com/cgi-bin/junco.pl/blogpost/524/15Jul2013/Forecastio-weather-API
• http://www.flickr.com/services/api/
• https://draftin.com/documents/54643?token=Qq1PuS1fL8Zr9yWDSefoeUMQCfp3yr1s6g_7ShYKops
  • Draft exposes its data through a REST API using JSON serialization and protected with OAuth 2. For testing or personal use, you can use basic authentication with your Draft email and password. But for using the API with other users, please use OAuth 2.
• http://www.instapaper.com/api/full

Top ones to view

https://draftin.com/documents/54643?token=Qq1PuS1fL8Zr9yWDSefoeUMQCfp3yr1s6g_7ShYKops

http://www.instapaper.com/api/full

http://micheltriana.com/2013/10/07/uri-design-rest-web-api/

http://micheltriana.com/2013/09/27/http-status-codes-in-rest-web-api/

http://micheltriana.com/2013/09/30/http-verbs-in-a-rest-web-api/

http://developers.box.com/get-started/

https://github.com/WhiteHouse/api-standards

http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful

https://stripe.com/docs/api#intro

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