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...
- Demo Switch In the demo church use the mode=demo parameter to bypass authentication. Example: https://demo.fellowshiponeapi.com/v1/People/123?mode=demo
- Resource Extensions Mode resources implement .xml, .json, .help, and .xsd
- Compression Use the HTTP header accept-encoding:gzip;compress to reduce the size of the payload.
- OAuth Test Harness This can be found at Developer.FellowshipOne.com/Test_Harness
- Code Libraries These can be found at GitHub.com/FellowshipTech
- Include Requirements & Contribution Sub Types
- User Case Story from Hope Community Church
- Group Search Categories and More
- Account Creation
- Single Sign On Functionality Exposed
- API Communication Value Changes
- API Enhancement: Create and Edit Groups!
- API Enhancement: Requirements Exposed
- Resource Versioning
- Enter Visitor Data via Your Church Website
- Fellowship One & Planning Center Online
- API Libraries and Sample Code
- Building a custom login for your church website using the API
- Roll Foward!
- The Agile Triangle
- Conversation Paralysis
- Picture this, image updates & creates through the REST API
- A REST API double shot : Groups and Events realms
- Increasing Software Delivery by 500%
- Quick people API realm update
- Introducing the new REST API giving realm
- Raising the bar…
- Building a Deployment Pipeline
- The World of Dev Craft
- Running Tests in Parallel with Selenium
- Abstracting Your Code to Remove Duplication
- Documentation in an Agile Environment
- Drowning in Debt
- Intro to Ruby on Rails
- API Strategy & Roadmap
- Staging/Sandbox Environment is Back up!
- Downtime in Sandbox/Staging Environment
- Android & OAuth
- F1 API Static Library with Objective-c
- Programming in F#
- NoSQL: HuMONGOus Benefits (Part 2)
- Our Scrum Team Structure
- SaaS & BI - The History & Future
- Getting Started with Android
- NoSQL: Leaving Schema Behind (Part 1)
- Your Feedback…and a $25 Gift Card!
- A Scrum Ceremony? Is this a wedding or something?
- Variables in PHP
- Data Exchange API Fixes
- F1 Check-in on the iPad
- Be the first to get the news & tips!
- An Introduction to PHP
- Working with Pop Up Windows in Selenium
- List Comprehension
- Source Control: A Time Machine For Your Source Code
- Developer Conference…Lower Price, Same Great Content!
- The Quality Assurance Team
- How does Fellowship Technologies manage complex projects?
- Developer Conference coming in May!
- Sandbox Refresh Complete
- Sandbox Refresh This Week
- Updates coming to the REST API
- Sandbox Environment Down Time
- F1Touch :: Fellowship One On The Go
- Under the Hood
- Sandbox Refresh Complete
- Sandbox Refresh Tomorrow (Oct. 2nd)
- Fellowship One Developer Forums
- Ten Commandments of API Consumption
- REST API Enhancements / Fixes deployed to Sandbox and Production 09.09.09
- Data Exchange URL cut-over complete
- Important Data Exchange URL changes
- Ron Nom Nom
- How to get started using the REST API