1. Restful APIs 101 Laura Heritage @heritagelaura

2. Agenda What is REST API Description Languages
Fundamentals of building REST
API Description Languages
RAML Basics for the class
Popular Implementation of REST
Akana API Management Platform
Project Commander

3. Building RESTful APIs

4. REST - Representational State Transfer
In Other terms:
The server will return the representation of the state of the resource

5. 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

6. Pragmatic

7. 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

8. 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
Snake case over camel case
snake case /accounts
camel case /Accounts
For associations: /resource/{id}/resourceIn
example: /accounts/1234/invoices

9. 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

10. 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

11. 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

12. 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.

13. 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

14. 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

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

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

17. 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

18. 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

19. 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

20. 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.

21. 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

22. API Security 5 Content Filtering 6 Rate Limiting
Authentication & Authorization 1 3
Message Security 2
App Key Validation/
Licensing 4
Threat Protection
Developers

23. Authentication/Authorization/SSO
Control and restrict access to your APIs
Make it easy yet secure
JWT

24. 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.

25. API Description Languages

26. What is an API Description Language (API DL)?
Blueprint
Contract
Metadata
Human Docs
Blueprint - It allows you to draw out what the potential API version can and should look like when it is completed.
Contract – It becomes the agreed upon contract between the consumer and provider
Metadata - houses the metadata which can be used in machine to machine communication or system to system interactions, primed for IoT
Instruction Manual - Human readable documentation is produced to all people to understand how to use the API

27. What About WSDL2.0 or WADL? For REST, they are not widely adopted
Both are not very “humanly readable”
Both are typically auto-generate from code – wouldn’t use them as a “blueprint” amongst non-technical types
WADL doesn’t contain enough information to adequately describe a RESTful API. Though does have extension points which are seldom used.
WSDL contains almost everything you need but is quite brittle. If it changes the clients must change too

28. Many API DL Are Available Today
WSDL
WADL
idDocs
Swagger
RAML
Hypermedia
API Blueprint
JSONDoc

29. Produce an API DL for Each API
Your consumers will use them too:
Generate SDK in their chosen language
Generate documentation they can augment for their audience
Import into their API Gateway to
Control and secure their own consumption of your API internally
Integrate with their backend systems
Orchestrate into a new API with value added services
Remember APIs are all about the consumption

30. What Language To Use To Implement RESTFul APIs?
Javascript Node.js (Express or restify)
Java – JAX-RS (Play Framework)
.Net
PHP – Lumen
Ruby – Sinatra
Perl - Mojolicious
Many more..

31. Tools Available For Hackathon
RAML API Designer
IDE for Node.js
Great for team development
Integrates with GitHub
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.

32. Today We Will Use RAML http://raml-designer.se.akana-dev.net:3999
Base off of YAML – human-readable data serialization format Tabbing is important!!! Helps you to create a blueprint for your API.

33. Demo Of API Designer

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

35. Demo of Cloud 9

36. Akana Overview

37. The Unified SOA & API Platform

38. API Platform Capabilities
Licensing
Quota Mgmt.
Partner Mgmt.
PCI Compliance
Provisioning
Policy Mgmt.
Monitoring
OAuth
Federation
Analytics
API Portal
Search
Documentation
Groups
Social
Gateway
Security
Authentication
Protection
IAM Integration
Encryption
Mediation
Quality of Service
Paging/Caching
Orchestration
Scripting
Analytics
Operational
Business
API
Policy Based
Embeddable Charts
OOTB Reports
Cust. Visualizations
Import
Export
Lifecycle
API/Services
Application
User
Compliance

39. Cloud, On-Premise or Hybrid

40. Project Commander Project Overview Current Status
Implement developer portals + API gateway for RPS, CPS & Elavon to simplify integration of partners apps w/ our APIs
Current Status
Payment Services
Elavon completed an external pilot in Q1. Elavon TOS team is using the gateway capabilities to the simplify expose & mgmt. of APIs and services
CPS has completed initial branding of their portal and development of a hosted API test platform. Working with TOS + Product and Support team to test capabilities; add portal documentation and develop support process flows prior to a Q1 ‘16 pilot
FSV (RPS’ pre-paid card subsidiary) has linked their portal with the API gateway and continue branding, API development, support process flows and portal documentation in advance of a Q1 ‘16 launch
Enterprise
We have discussed API management, development & expose use case with the Elan, Wealth Mgmt., Treasury Mgmt. and Wholesale Bank organizations

41. Elavon Developer Portal - Internal Use of the Gateway
Elavon GTS (TOS) team has been using the API gateway to simplify API management and add security in the following use cases:
Expose the Global Merchant Boarding API. Implementation for the Brazil & Mexico JVs has been completed with other markets to follow shortly. (The boarding API is used by internal Elavon Ops. Teams, bank & MSP partners.)
Use Global Boarding API to integrate with USB Fusion system for the “One & Done” Project, to enable cross selling of products between USB and Elavon
Leveraged the gateway to simplify connectivity/add security for alternative payment networks in Brazil
Connecting Elavon.com to the PCI Compliance database which is part of Elavon’s new PCI Compliance Manager program.
Made the Enterprise Imaging service available to Ops staff so they can upload images to FileNet for partners/merchants to retrieve statement images
Using the gateway is lowering the support overhead on managing internal services and APIs that are exposed (e.g. access management, reporting, etc.)

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

43. Back Up Reference Slides

44. What is Idempotence?
Clients can make the same call repeatedly while producing the same results
Making multiple identical requests has the same effect as making a single request
The response my not be the same. E.g a resource’s state may change between requests.
PUT and DELETE are Idempotent
GET, HEAD, OPTION and TRACE are Safe methods and therefore Idempotent
POST is Unsafe