The PHP podcast where everyone chimes in.

Originally aired on

September 22nd, 2014

004: All About API's

All about web API's: designing your API with RAML, authentication with OAuth and discussing the hypermedia-constraint (HATEOAS).


All About Web API's, RAML, OAuth, & HATEOAS Show Summary

All about web api's, it's a very broad term...Application Programming covers a lot of things but today we are talking about web api's. We're going to be exploring terms like REST and JSON, what you need to do to consume an api from a php perspective, and from a client side perspective, and moving app domain logic into the client side, Single Page Applications (SPA) - tend to be very JavaScript intensive.

  • What is an api?
    • Fundamentally, the way two pieces of software talk to each other.
    • REST Principles
    • At a high level, it's like a contract, it's a defined set of rules and language.
      • Breaking backwards compatability, but you're breaking the contract.
  • Why build an api?
    • Everything is connecting to something else, so if you build an app, you will need to connect to some other service.
    • api first design
    • as the world grows, connection is what it's all about now.
  • Some developers, don't realize that they're using an api due to the api being buried in a package. Like AWS S3 Package.
  • Consuming an API vs designing an API
  • Creating an API allows for more flexibility, you can create a mobile version that consumes an api as well as a desktop or it allows another service to connect with your app.
  • Consuming an api differs from a database because it forces you to account for situations where the api may fail. Apis tend to have more exceptions than a DB layer like PDO, so you need to be more aware when programming.
  • What does a web api look like?
  • The HTTP Protocol verbs are intended for specific purposes and you need to understand them and use them accordingly
  • Using the proper response codes.
  • APIs are distributed systems, meaning latency comes into play
  • You have to design for failure big time
  • Design an api based on failure cases (they're the hard ones), success cases are the easy ones.
  • When working with apis, error handling is no exception. (buh dum tiss)
  • (Give it a REST @jmikola)
  • The podcast descends into punfest
  • 16:20 - 18:00 - general discussion about how apis work (getting data, updating a resource, delete)
  • 18:30 - 20:20 - Good discussion about what happens in an api request. Headers are sent, the api reads the headers and determines if it can respond, then proceeds, then it processes the request and returns the content...general browser users never see the headers of an API...but basically everything is determined by the headers.
  • 21:20 - 24:40 - Talking through a server request, one guy acts as server another as browser and basically talk through what they want to do from the perspective of the technology that they are representing.
  • 24:40 - 25:00 - Talking through an invalid response, props to knowing the server code for a 'too large request' code
  • 25:00 - 25:40 - Talking about what the status codes
    • 200s - Success status
    • 300s - Deal with Redirecting
    • 400s - Deal with errors
  • 26:15 - 26:45 - Why is JSON better than XML?
    • In php world, JSON is way easier to parse than XML
  • 26:45 - 27:30 - URL vs URI? What's the difference?
    • URI - Is more proper, stands for Uniform Resource Identifier, it's an ID, not necessarily a location
    • They're pretty much interchangeable
    • URL - Universal Resource Location
  • 27:30 - 32:00 - REST - What is it? Why is it important in API design?
    • Different types of APIs, SOAP and REST are just two of the types.
    • Most APIs are not RESTFUL
    • 28:35 - HATEOAS - Stands for Hypermedia As The Engine Of Application State
      • Think of it as a "Choose your own adventure" book
      • Github is an example of a HATEOAS API
  • 32:00 - REST and RESFTUL. HATEOAS is the extreme form of REST or as REST api people say "The correct form of REST"
  • 32:18 - RPC style of api
  • 33:00 - REST was designed to give you longevity with your api
  • REST gives more flexibility than RPC or SOAP
  • 33:41 - 35:00 - RPC stands for Remote Procedure Call
    • local functions that map one to one with remote functions in the api
    • REST is more resource oriented and RPC is more function or feature oriented
  • 35:00 - APIs are not limited to data, although that is how most of the web thinks of them.
  • 36:00 - SOAP requires a lot of information in the request that doesn't seem relevant to what you need to get, making it a bit of a pain to work with.
  • 37:30 - JSON tends to be preferred because it is faster than XML, usually because the payload is less to transfer. Additionally SOAP has a lot of payload in the headers.
  • JSON is great for the mobile concern of payload, which translates to data transfer.
  • 39:12 - Roy Fielding - father of REST
  • Knee slapper by @jmikola - I gave up on SOAP API, it was a wash.
  • 40:00 - 41:00 - Richardson Maturity Model
    • First level is XML of HTTP...although now JSON is probably preferred.
    • Nouns, thinking of your api as a series of resources that are interconnected, that have relationships that can be interacted with one at a time, like named resources
    • Verbs, using the HTTP verbs correctly, GET, POST, PUT, DELETE...maybe Head.
    • Hypermedia controls. (Choose your own adventure book)
  • 42:19 - Matt Frost book on oAuth
  • 42:45 - 45:30 - discussion about how oAuth works.
  • 46:00 - Basic Auth
    • Avoid probably, transmits password in plain text.
  • 48:30ish - Talking about using a secret key and hashing the request so that the server can decrypt based on your key.
    • Supposed to allow the ability to wireframe an API
    • Advantage is that you can sort of test an api without having to write code...or invest a lot of time to begin testing an api that would require you to be committed once you begin being able to test the api.
    • It's basically a spec
  • 56:40 - SWAGGER - Another API modeling language
  • It's darn right impossible to change an api after it's been developed
  • Swagger seems to be more about documenting an api that you have already created, where RAML is more about being able to spec out and prototype an API
  • Semver - semantic versioning
  • 58:00 - using semver to version an api
  • Designing an api is about solving a business problem...if you're not solving a business problem with your api, you're doing it wrong.
  • This is where RAML can be beneficial, so that you don't spend a lot of time writing code, and can focus a bit on what you're api does and how it should work.
  • Apigility
  • Runscope
    • Proxy between you and an api, helps with debugging an api
  • Ways to test apis
  • HTTP old, but still awesome
  • new HTTP RFCs - new definitions of the spec for HTTP
  • 1:21 - End of show, after party begins, hilarity ensues

Show note credits

A huge thank you to Andrew Huggins for creating the show notes for this episode!


Matt Frost

Jeremy Lindblom

Mike Stowe

Keith Casey Jr

Andrew Curioso

Show Notes Credit

Thank you Andy Huggins for authoring the show notes for this episode!

If you'd like to contribute show notes and totally get credit for it, check out the show-notes repo!