1. Restful APIs 101 Laura Heritage @heritagelaura

2. Agenda
REST Fundamentals
Akana API Designer
Cloud9 and Ionic

3. The Glory of REST Richardson’s Maturity Model
Roy Fielding definition of RESTFul
HATEOAS
GET, PUT, POST, DELETE
/books/1 and /books/2
POST
Ah the Glory of REST what we all should aspire to. Or should we?
This Maturity Model is pretty popular in the industry now especially around the hypermedia arena. If this is your first time seeing it let me explain the levels and you can see where you fall
Level 0: You could consider this plain old XML. You have a single endpoint in which you send a request and you get back an XML response and then then you send the next request. (Normally POST) Typically SOAP request here
Level 1: Resources are introduced. Still this level usually only uses one method like POST
Level 2: Next level is the Verbs (GET, PUT, POST, DELETE) and using the appropriate response codes. For example when something goes wrong, don’t just use 200 (OK)
Level 3: Level uses HATEOAS to deal with discovering possibilities of your API (Hypermedia as the Engine of Application State)
Richardson’s Maturity Model

4. Pragmatic

5. REST is Made Up of Resources and Actions
Resource - An Entity that you want to expose that can be named
For example: accounts, users, invoices, transactions
Actions – What you can preform on the Resources using the HTTP method GET, PUT, POST, DELETE, PATCH
GET /accounts – Retrieves a list of Accounts
POST /accounts – Creates a new Account

6. Basic REST Guidelines (Principles)
2 URI’s per resource
1. Listing (collection) - /v1/accounts
2. Detail - /v2/accounts/{id}
Use nouns instead of verbs to name resources
WRONG: /v1/getAllAccounts
CORRECT: /v1/accounts
Prefer plurals over singular: /accounts over /account
lower case over camel case
lower case /accounts
camel case /Accounts
For associations: /resource/{id}/resourceIn
example: /accounts/1234/invoices

7. Accounts URL Endpoints
Use Case
What you are tempted to do:
Proper REST URL
To get all Accounts
/v1/get-all-accounts
/v1/accounts
To get a particular Account
/v1/get-account/{id}
/v1/accounts/{id}
To create an Account
/v1/create-account/{id}
To delete an Account
/v1/delete-account/{id}
To update an Account
/v1/update-account

8. Tell The Server What Action to Perform
HTTP Request Method
Maps To:
CRUD Operation
GET
->
Read (Show)
POST
Create
PUT
Update (the whole resource)
DELETE
Destroy
PATCH
Update (updating a partial resource)
OPTIONS
Allowed Verbs (Not used too often)
HEAD
Headers Only

9. Accounts URL Endpoints
Use Case
HTTP Method:
Proper REST URL
To get all Accounts
GET
/v1/accounts
To get a particular Account
/v1/accounts/{id}
To create an Account
POST
To delete an Account
DELETE
To update an Account
PUT

10. What About Relationship?
Linked Resources
/v1/accounts/{id}/invoices
/v1/accounts/{id}/billing_info
To embed or not?
If a resource can live independently then do not embed.
If it can not live independently then embed.

11. Keep complexity behind the “?”
Variations
Keep complexity behind the “?”
/accounts?type=corporate&country=us
/accounts?type=consumer&country=uk
/billing_info?type=credit_card
/billing_info?type=checking

12. Pagination /accounts?limit=25&offset=50
Send total entries back to user – For example, in custom HTTP header: X-Total-Count
Provide links to next or pervious page - For example in HTTP header: Link

13. Version /v1/accounts /v2/accounts
While there are several ways to represent versions. This is the preferred method
/v1/accounts /v2/accounts

14. Give Me Exactly What I Need
And no more..
/accounts?fields=first_name,last_name,address

15. HTTP Codes and Messages
HTTP Codes are for Code
HTTP Status Code: 401
Message is for people
{ “Status” : “401”,
“messsage”: “Authenticate”, “code” : 20003,
“moreinfo” : }
This is the best. When you provide a link to more information

16. Types of Status Codes Success - Everything worked
Client error - The application did something wrong
Server error - The API did something wrong
200 - OK
400 - Bad Request
500 - Internal Server Error

17. Top 10 HTTP Codes 200 OK 201 CREATED 204 NO CONTENT 400 BAD REQUEST
401 UNAUTHORIZED
403 FORBIDDEN
404 NOT FOUND
405 METHOD NOT ALLOWED
409 CONFLICT
500 INTERNAL SERVER ERROR

18. What If It Doesn’t Fit To CRUD
First Make Sure it Really Doesn’t
Restructure the action to appear like a field of a resource.
This works if action doesn’t take parameters
For example the activate action could be mapped to a boolean activated field and updated via PATCH to the resource
Treat like a sub-resource with RESTful principles.
For example, GitHub’s API lets you star a gist with
PUT /gists/:id/star Star a gist
DELETE /gists/:id/star - Unstar a gist
Sometimes you have really no way to map the action to a sensible RESTFul structure.
For example, a multi-resource search doesn’t really make sense to be applied to a specific resources endpoint.
In this case, /search would make the most sense even though it isn’t a resource.

19. Don’t Expose The Complexities Of Your Existing Information System
Design for the developer audience who is going to use it.
Application
API Layer
Client
Application
Interface
/entrypoint
/collection1
/resource 1
/resource 2
/collection
/resource1
/resource2 ….
HTTP
Client App
REST Library
Optional
HTTP Library
Application
Data Model
Resource Model
server
client

20. How Akana Fits Into Your Existing Architecture
Security Services

21. Additional Recommended Practices
Treat each API as a product
Know your audience and their use cases
Design for consumption
Document wisely – they shouldn’t need to know the internal architecture to use your API
Ensure great intuitive error handling
Offer both JSON & XML
Use HTTP headers for serialization format
Content-Type
Accept
GET methods and Query parameters should not alter state
Look at great APIs in the market and steal concepts from them.

22. Tools Available For Hackathon
Developer Portal
API Designer
API Creation
IDE for Node.js
Great for team development
Integrates with GitHub
Open source mobile SDK for HTML5
Based on Node.js and Cordova
Allows you to rapidly build mobile applications
Server Side Javascript
We will be leverage Express – A framework on top of Node.js to build RESTful APIs
Open-source document database - highly performant, high availability, automatic scaling.

23. Demo Of Akana Portal

24. Today We are Using Node.JS On Cloud 9

25. Demo of Cloud 9

26. Install Ionic in Cloud9 Create a Node.js workspace
From the workspace’s terminal run:
npm i cordova ionic -g
ionic start myApp
cd myApp
ionic serve -a $IP -p r 8081

27. To Add a New Tab To myApp Example
Create New Factory (usbankservices.js
Modify controllers.js
Create new tab (tab-usbank.html)
Modify tads.html
Modify index.html
Modify app.js

28. usbankservices.js

29. index.html

30. Controller.js
Add a controller

31. tab-usbank.html

32. tabs.html

33. App.js

34. Download code npm i myappUSBankExample
cd to node_module/myappUSBankExample
npm install
ionic serve -a $IP -p r 8081

35. API Resources and API University
Resource Center
Follow us on:

36. Back Up Reference Slides