Extreme APIs for a better tomorrow

EXTREMEAPIS

for a better tomorrowhttp://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

http://www.aaronmaturen.com/api 2

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 InterfaceREST => REpresentational State Transfer


Data is messy.


Data is confusing.


Conventions?

DEAN_ROLECHAIR_ROLEEmployeeRoleDeanRole2DeanRole3ChairRole2ChairRole3ChairRole4


Descriptive Names?

Printed_Text


Data is everywhere.



Leverage HTTPCreate => POSTRead => GetUpdate => PUT / PATCHDelete => DELETE


Leverage HTTP for Collectionshttp://api.svsu.edu/courses

POST => Update entire collectionGET => Retrieve the entire collectionPUT => Replace the entire collectionPATCH => Modify the collectionDELETE => Delete the entire collection


Leverage HTTP for elementshttp://api.svsu.edu/courses/courseNumber

POST => Update a single course elementGET => Retrieve a single course elementPUT => Replace a single course elementPATCH => Modify a single course elementDELETE => 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" // ... attributes of this post }, { "id": "2" // ... attributes of this post }]}


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/courseshttp://www.aaronmaturen.com/api 23

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


{ "persons": [{ "firstName": "Aaron", "middleInitial": "T", "lastName": "Maturen", "email": "[email protected]", "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 OK201 - Created something OK202 - Accepted but is being processed async (for a videomeans encoding, for an image means resizing, etc)


3xx is all about redirection

301 - Moved permanently302 - Moved temporarily304 - Not Modified


4xx is all about client errors

400 - Bad Request (should really be for invalid syntax, butsome folks use for validation)401 - Unauthorized (no current user and there should be)403 - The current user is forbidden from accessing this data404 - That URL is not a valid route, or the item resource doesnot exist405 - Method Not Allowed410 - Data has been deleted, deactivated, suspended, etc418 - I'm a teapothttp://www.aaronmaturen.com/api 30

5xx is all about service errors

500 - Something unexpected happened and it is the API's fault503 - API is not here right now, please try again later507 - Hard-drive filled up.


Custom error codes and messages


HTTP/1.0 401 UnauthorizedDate: Fri, 19 Oct 2014 16:59:59 GMTContent-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 UnauthorizedDate: Fri, 19 Oct 2014 16:59:59 GMTContent-Type: application/vnd.api+json{ "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 OKand

Error Code


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

EVER.


TransformersTables 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_ROLECHAIR_ROLEEmployeeRoleDeanRole2DeanRole3ChairRole2ChairRole3ChairRole4


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

LocationDescBuildingDescPriCampusOfficePriCampusPhonePriCampusFax


Offices are nicer

{ "persons": [{ "firstName": "Joni", "middleInitial": "M", "lastName": "Boye-Beaman", "office": { "location": "SVSU Main Campus", "phone": "989-964-4062", "room": "Wickes Hall 363", "hours": null }, ... }]}


Degrees are nicer

Degree1Degree2Degree3Degree4DegreeInSta1DegreeInSta2DegreeInSta3DegreeInSta4


Degrees are nicer

{ "persons": [{ "firstName": "Joni", "middleInitial": "M", "lastName": "Boye-Beaman", "degrees": [{ "degree": "Doctor of Philosophy", "from": "State Univ New York-albany" }], ... }]}


Hiding Schema UpdatesBefore

'firstName' => $person->nickName,

After

'firstName' => $person->firstName,


Hiding Schema UpdatesBefore

'status' => $person->status,

After

'status' => $person->status === 'a' ? 'available' : $person->status ,


Objects will be related


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


{ "departments": [{ "department": "CS", "colleges": { "college": "SC", "description": "Science Engineering & Technology", "deans": [{ "firstName": "Andrew", "middleInitial": "M", "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


PaginationGET /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 FERPAOh 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 rescueGET /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 apage 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: "[email protected]", password: "secret", scope: "read_users", state: "123456789" }


HTTP/1.0 200 OKDate: Sun, 19 Oct 2014 16:59:59 GMTContent-Type: application/vnd.api+json{ "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?


Internet

Extreme APIs for a better tomorrow