Extreme APIs for Better Tomorrow

EXTREME
APIS
for a better tomorrow
http://www.aaronmaturen.com/api 1

I'm Aaron.
• I work at Saginaw Valley State University in Michigan
• I normally write in PHP and JavaScript
• I am going to try to keep this (mostly) langauge agnostic
http://www.aaronmaturen.com/api

I have a small company (Ivory Penguin) to do side jobs

Interrupt me
whenever

Interrupt me if you
have a question
It's easy to forget it

Interrupt me if I'm
talking too fast
I get excited easily

What is an API?
API => Application Programming Interface
REST => REpresentational State Transfer

Data is messy.

Data is confusing.

Conventions?
DEAN_ROLE
CHAIR_ROLE
EmployeeRole
DeanRole2
DeanRole3
ChairRole2
ChairRole3
ChairRole4

Descriptive Names?
Printed_Text

Data is everywhere.

Leverage HTTP
Create => POST
Read => Get
Update => PUT / PATCH
Delete => DELETE

Leverage HTTP for Collections
http://api.svsu.edu/courses
POST => Update entire collection
GET => Retrieve the entire collection
PUT => Replace the entire collection
PATCH => Modify the collection
DELETE => Delete the entire collection

Leverage HTTP for elements
http://api.svsu.edu/courses/
courseNumber
POST => Update a single course element
GET => Retrieve a single course element
PUT => Replace a single course element
PATCH => Modify a single course element
DELETE => Delete a single course element

{json:api} 1
If you've ever argued with your team about the way your JSON
responses should be formatted, JSON API is your anti-bikeshedding
weapon.
By following shared conventions, you can increase productivity,
take advantage of generalized tooling, and focus on what
matters: your application.
1 http://jsonapi.org/

A JSON object MUST be at the root of every document.
A document's top level SHOULD contain a representation of
the resource or collection requested.
The primary resource(s) SHOULD be keyed either by their
resource type or the generic key "data".

{
"posts": {
"id": "1",
// ... attributes of this post
}
}

{
"posts": [{
"id": "1"
}, {
"id": "2"
}]
}

GET /prefixes HTTP/1.1
Host: api.svsu.edu

{
"prefixes": [
{
"prefix": "ACCT",
"description": "Accounting"
},
{
"prefix": "ART",
"description": "Art"
},
...
]
}

Plural v. Singular
/persons
/person/23
Mixing it up starts to get confusing
/persons
/persons/23
/persons/23/courses

Query Strings
GET /persons?name=Aaron%20Maturen HTTP/1.1
Host: api.svsu.edu

{
"persons": [{
"firstName": "Aaron",
"middleInitial": "T",
"lastName": "Maturen",
"email": "atmature@svsu.edu",
"division": "Administration & Business Affairs",
"department": "Information Technology Services",
"program": "Administration & Business Aff.",
"title": "Developer",
"office": {
"location": "SVSU Main Campus",
"phone": "989-964-2190",
"room": "South Campus Complex B 117",
"hours": null
},
"degrees": [...],
"ferpa": true,
"username": "atmature",
"faculty": false,
"academicDepartment": false
...
}]
}

ERROR

HTTP Status Codes

2xx is all about success
200 - Generic everything is OK
201 - Created something OK
202 - Accepted but is being processed async (for a video
means encoding, for an image means resizing, etc)

3xx is all about redirection
301 - Moved permanently
302 - Moved temporarily
304 - Not Modified

4xx is all about client errors
400 - Bad Request (should really be for invalid syntax, but
some folks use for validation)
401 - Unauthorized (no current user and there should be)
403 - The current user is forbidden from accessing this data
404 - That URL is not a valid route, or the item resource does
not exist
405 - Method Not Allowed
410 - Data has been deleted, deactivated, suspended, etc
418 - I'm a teapot

5xx is all about service errors
500 - Something unexpected happened and it is the API's fault
503 - API is not here right now, please try again later
507 - Hard-drive filled up.

Custom error codes
and messages

HTTP/1.0 401 Unauthorized
Date: Fri, 19 Oct 2014 16:59:59 GMT
Content-Type: application/vnd.api+json
{
"error": {
"type": "OAuthException",
"message": "Session has expired at unix time 1385243766.
The current unix time is 1385848532."
}
}

HTTP/1.0 401 Unauthorized
Date: Fri, 19 Oct 2014 16:59:59 GMT
{
"error": {
"type": "OAuthException",
"code": "ERR-01234",
"message": "Session has expired at unix time 1385243766.
The current unix time is 1385848532."
"documentation_url": "/docs/errors/#ERR-01234"
}
}

200 OK
and
Error Code

If it's a 2xx code.
It doesn't get an error code.
EVER.

Transformers
Tables in disguise

It's normally a very bad idea to
just output a db table through
your API

You're ...
• revealing your database structure
• probably returning incorrect value types
• returning everything
• tightly coupling your api to the database

Remember our poorly named fields?
DEAN_ROLE
CHAIR_ROLE
EmployeeRole
DeanRole2
DeanRole3
ChairRole2
ChairRole3
ChairRole4

Those get cleaned up quite nicely
{
"persons": [{
"firstName": "Joni",
"middleInitial": "M",
"lastName": "Boye-Beaman",
"division": "Academic Affairs",
"department": "College of Arts & Behavioral Sciences",
"title": "Dean College of Arts & Behavioral Sciences",
"dean": true,
"chair": false
...
}]
}

Offices are nicer
LocationDesc
BuildingDesc
PriCampusOffice
PriCampusPhone
PriCampusFax

Offices are nicer
{
"persons": [{
"office": {
"location": "SVSU Main Campus",
"phone": "989-964-4062",
"room": "Wickes Hall 363",
"hours": null
},
...
}]
}

Degrees are nicer
Degree1
Degree2
Degree3
Degree4
DegreeInSta1
DegreeInSta2
DegreeInSta3
DegreeInSta4

Degrees are nicer
{
"persons": [{
"degrees": [{
"degree": "Doctor of Philosophy",
"from": "State Univ New York-albany"
}],
...
}]
}

Hiding Schema Updates
Before
'firstName' => $person->nickName,
After
'firstName' => $person->firstName,

Hiding Schema Updates
Before
'status' => $person->status,
After
'status' => $person->status === 'a' ? 'available' : $person->status ,

Objects will be
related

Inclusion of Linked Resources
GET /departments/?embed=colleges.deans HTTP/1.1
Host: api.svsu.edu

{
"departments": [{
"department": "CS",
"colleges": {
"college": "SC",
"description": "Science Engineering & Technology",
"deans": [{
"firstName": "Andrew",
"lastName": "Chubb",
...
}]
...
}]
}

Obscurity

Remember the example from
before...
GET /persons/23 HTTP/1.1
Host: api.svsu.edu
This is better
GET /persons/66dc3930-5928-11e4-8ed6-0800200c9a66 HTTP/1.1
Host: api.svsu.edu

Pagination
GET /persons/teaches=Y HTTP/1.1
Host: api.svsu.edu
• Downloading more stuff takes longer
• Your database might not be happy about trying to return
100,000 records in one go
• Presentation logic iterating over 100,000 records is also no
fun

{
"persons": [ ...],
"pagination" : {
"total": 1262,
"count": 12,
"per_page": 12,
"current_page": 1,
"total_pages": 107,
"next_url": "/persons?page=2&number=12",
}
}

{
"persons": [ ...],
"pagination": {
"cursors": {
"after": 12,
"next_url": "/places?cursor=12&number=12"
}
}
}
If the API returns 12 persons then there might be a next page.

Lions, and Tigers, and FERPA
Oh my.
We're not returning anything protected by FERPA to
anonymous users
GET /persons?name=Student%20McStudent HTTP/1.1
Host: api.svsu.edu

persons: [{}]
We could have returned an unauthorized
error (401), but we decided to just act like
we didn't find anything

OAuth to the rescue
GET /persons?name=Student%20McStudent HTTP/1.1
Host: api.svsu.edu
Authorization: Bearer qxacJ57Yo5XEhzExjsJgLleLoBRXz7kn9ySFB3sY
may return
persons: [{
firstName: "Student",
...
}]

OAuth Grant Types
• Authorization Code
Typical third party workflow, takes user to a common login
page, they enter their credentials, they are taken to a
page that explains which rights the application would like to
have and the user approves it.

OAuth Grant Types
• Password (user credentials)
User Credentials are possibly the easiest way to get an
access token for a user. It skips the whole redirect-flow that
“Authentication Code” provides Internal Apps Only
• Refresh Token
Users receive a 401 when the access token expires and the
client automatically requests a new one with it's refresh
token

OAuth Grant Types
• Client Credentials
The application will not have any context of a “user”, but it
will be able to interact with your API. This is useful for CRON
jobs, worker processes, daemons or any other sort of
background process.
• Custom Grant Type
You're free to add any new grant types that you would like

POST /oauth/access_token HTTP/1.1
Host: api.svsu.edu
{
grant_type: "password",
client_id: "98f9bc2f27159248b3e51fa9fd91a5f9",
client_secret: "7329d92ebf23efc145b7370d5f4fbf32",
username: "atmature@svsu.edu",
password: "secret",
scope: "read_users",
state: "123456789"
}

HTTP/1.0 200 OK
Date: Sun, 19 Oct 2014 16:59:59 GMT
{
"access_token": "qxacJ57Yo5XEhzExjsJgLleLoBRXz7kn9ySFB3sY",
"token_type": "bearer",
"expires": 1400880256,
"expires_in": 604800,
"refresh_token": "hHgKUskwd9Ukr08CtynO8PjHcV1CZICi1yU3nNmo"
}

What's Next?

API Clients
• PHP
• JavaScript (AngularJS Resources)

Apps
• Course Lookup
• Employee Directory
• Student Voting
• Grant logging
• HealthyU

Password Authentication
• Login to the API and the Application simultaneously
Authorization Code
• Allow students and third parties to access our data
• Users are notified that the application is not created by IT
and informed of what rights it is requesting

Questions?
Comments?
Concerns?

Extreme APIs for Better Tomorrow

Recommended

Recommended

More Related Content

What's hot

What's hot (19)

Similar to Extreme APIs for Better Tomorrow

Similar to Extreme APIs for Better Tomorrow (20)

Recently uploaded

Recently uploaded (20)

Extreme APIs for Better Tomorrow