Ten Commandments of API Consumption

The Fellowship Technologies team worked hard to give you an API interface that is based on patterns, practices, and protocols. As developers we see that there is major value in sticking with something that is "tried and true," so below we have provided you with ten basic guidelines for consuming the REST API. The first 5 commandments are to help consumers interact with the API. The last 5 are how consumers can interact with others in the community to grow, learn, and build.

Thou Shalt Check HTTP Status Codes

Status codes are tremendously important when dealing with a web based API. They tell you what happened, what will happen, and how to respond to everything in-between. The API uses all status codes according to the HTTP 1.1 specification. This means that if you create a person, then the API will send back a 201 Created, or if you delete an address and try to request it, you'll get back a 410 Gone. The proper use of status codes are instrumental when we as developers interact with the internet; they should be given some serious attention developing web based software. Have a look at the status codes that we've implemented to make your API consumption more enjoyable.

Thou Shalt Not Take The REST Name in Vain

...or at least you should consider what this Architecture can do for you. A REST based API implementation uses things like hyper media (linked resources defined by the server) and avoids things such as out of band information to make consuming the API much like consuming a web page. All of our resources have URIs associated with any resource that can be referenced. This helps the consumer avoid confusing custom metaphors and gives you one place of reference. REST APIs are perfect for web consumption, so try to use them with that in mind. Massive transactions and huge data in or out might not be the best approach, but simple, "thick-grained" resource consumption is.

Thou Shalt Call EDIT Before UPDATE

There are basic tenants of any application that "help" to make it work; things you can stand on, so that you can feel safe and secure. One such tenet is that it is a really good idea to call EDIT ([GET]https://demo.fellowshiponeapi.com/v1/People/123/edit) before calling UPDATE([PUT] [POST(Low REST)] https://demo.fellowshiponeapi.com/v1/People/123) on all resources.

By calling EDIT you'll get the latest state of the resource you are about to update, otherwise you're likely to run into concurrency issues, overwrite data, or run the possibility of putting bad data into the system.

  • Call EDIT before UPDATE
  • Call SHOW before DELETE
  • Call NEW before CREATE

Make sure to have a look at the docs for more information on these behaviors and implementations.

Thou Shalt Consider the OAuth Protocol Usage (2nd or 3rd Party)

This is an easy one. Are you a developer / organization that is writing something for everyone (3rd Party) or are you creating something just for your organization or a single user base (2nd party)?

2nd Party User Trusted Consumer Applications (info)
Defined as applications written and made private by the Consumer and used by the Consumer's (or Tenant's) Users - They will be marked as Private.
3rd Party Consumer Applications (info)
Defined as applications written and made public for consumption across Tenants - They will be marked as Public.

Thou Shalt Use the "Hyper" Aspects of the REST API

Since this API is based on a REST architecture every resource has a corresponding address. So when you ask for a person ([GET]/People/1) you'll get the resource with links for the person's household, status, occupation, etc... This is tremendously valuable because you not only get context for your resources, but you also need not worry about storing any out of band information on the resource.

That metaphor is carried throughout the API: When a consumer creates a person, the location header will contain a URI for the new person. When you get a resource the content-location will contain a URI for the resource. The same goes for 301's and 204's and so on.

Thou Shalt Not Murder the API

While currently there are no consumption thresholds we reserve the right to "pull the plug," so to speak, on any application that demonstrates aberrant consumption of the REST API. Simply be mindful of usage, your users will love you for it and so will the API.

Thou Shalt Share Code and Lessons Learned

The developers at Fellowship Technologies love to give stuff away. Code, ideas, help, t-shirts, etc... Not because we are some rag-tag bunch of philanthropists but because it's the right thing to do. When you're passionate about something, like code, that passion is infectious and you want to share. Since you guys are the smart ones, our hope is that you feel the same way. The more we give back to each other them more we grow and get to play with some really cool stuff.

Thou Shalt Take Community Content

It's out there for you and your organization. Take it, use it, make it better.

Thou Shalt Help Thine Neighbor When in Need

Have you ever run into a road block? Of course you have, and most likely someone out there has faced the same or a similar barrier. Most of us might head to Google or Stack Overflow, rub the magic search box, and "poof" out pops the answer. Those answers came from somewhere / someone. If you can help with whatever programming roadblock someone is in, go for it - you're sure to get satisfaction from helping others and you might just get some street cred and some coin for your efforts.

Thou Shalt Help Thineself When A Neighbor is not Around

Sometimes it's unfortunate and there's just not a neighbor around to help. What do you do then? The answer...make sure you have used all the tools at your disposal. A few of these tools include...

Categories:

Previous Posts:


Subscribe to the RSS feed!