1 of 13

A Series of Unfortunate Requests

YAPC::NA 2015

Joseph Hall

2 of 13

Who am I?

  • Not this guy
  • Perl hacker since 1999
  • Python hacker since 2010
  • Second contributor to Salt
  • Salt Cloud lead dev
  • SaltStack’s “API Guy”
  • Classically trained chef

3 of 13

The Beauty of REST

  • HTTP is ubiquitous
  • Coders are used to HTTP methods
  • HTTP is easy to mess with
  • Many REST APIs are very similar
  • REST connects otherwise different systems

4 of 13

JSON vs XML

  • XML used to be awesome
    • Because XML was like HTML
    • And HTML was easy to write in
  • JSON is more awesome
    • Less chatty than XML
    • JSON looks like a hash
      • XML has to have data shoehorned into it

5 of 13

JSON and XML in REST

  • Many APIs still use XML
  • But the majority are moving to JSON
    • Even some old APIs are converting
  • If your API is using JSON, it will be easier to work with

6 of 13

Common REST Methods

  • GET: View/list information
  • POST: Create information
  • PUT: Replace information
  • PATCH: Update information
  • DELETE: Remove information

7 of 13

REST Authentication

  • Very common
    • Username/Password
    • Token(s)
  • Somewhat common
    • OAuth/OAuth2
    • Signature calculation
  • Less common
    • Client-side certificates

​

8 of 13

Breaking Down REST URLs

<proto>://<api_url>/<resource>[/<action>]

  • proto: Protocol (HTTP, HTTPS)
  • api_url: Domain and maybe path (api.github.com, api.stormpath.com/v1)
  • resource: What will be accessed (users, roles, machines)
  • action: What to do (create, list, show)

9 of 13

Example 1: GitHub

https://api.github.com/repos/saltstack/salt/issues/15000

  • api_url: api.github.com
  • resource: repos/saltstack/salt
  • action: issues/15000
  • Auth: Basic, OAuth2 token (header or param), OAuth2 key/secret (param)

10 of 13

Example 2: Joyent

https://us-west-1.api.joyentcloud.com/<account>/users

  • api_url: us-west-1.api.joyent.com
  • resource: <account>
  • action: users
  • Auth: Signature

11 of 13

Example 3: Stormpath

https://api.stormpath.com/v1/accounts/<account_id>

  • api_url: api.stormpath.com/v1
  • resource: accounts
  • action: <account_id>
  • Auth: Basic, with API id/key as username/password

12 of 13

Example 4: SaltAPI

http[s]://<saltmaster>/<resource>[/<resource_id>]

  • api_url: <saltmaster>
  • resource: <resource>
  • action: <resource_id>
  • Auth: Basic and/or token

13 of 13

Contact

​

@techhat

@techhat

@techhat

blog.josephhall.com