Web APIs

CS418 - Web Programming - Spring 2015

Old Dominion University

Mat Kelly (mkelly@cs.odu.edu)

What is a Web API?

  • Routines, protocols, and tools for building software application
  • Exposes commands on a closed system
  • List of commands and how to interact with system
  • Software-to-software interface, not a UI
  • Formally defined set of standard specifications
  • HTTP for data other than web pages
  • Mitigates having to reinvent the wheel for data access
    • Discourages scraping


  • REpresentational State Transfer
  • Usually communicates over HTTP
    • with GET, POST, PUT, DELETE, etc.
  • Predecessor Simple Object Access Protocol (SOAP)
      • has envelope, header, body, and fault fields

SOAP Example (for comparison)

POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 299
SOAPAction: "http://www.w3.org/2003/05/soap-envelope"

<?xml version="1.0"?>


Comparing REST & SOAP

  • Lightweight alternative to
    • RPC (Remote Procedure Call)
    • Web Services (SOAP, WSDL, etc)
  • No official standard for RESTful APIs (unlike SOAP)
    • REST is architectural, SOAP is a protocol
    • REST is simple enough to roll-your-own implementation

REST Definitions

  • base URI:
    • http://wsdl-docker.cs.odu.edu:60020/paths/are/ok/too/
  • media type (e.g. JSON, XML, etc)
  • allowed HTTP methods (GET, POST, etc.)
  • links to reference state
  • links to reference related resources

Simple REST Communication

  • Above is simply the URI, not the message body
    • Implicit HTTP GET
  • Can be tested with a browser
  • Response is an HTTP reply, not embedded in anything
  • Use nouns, not verbs in URI schemes

REST - additional parameters

  • For longer or binary parameters, use HTTP POST
  • GETs should only be used for read-only queries and not have side-effects
  • For creation, updating, and deleting, use POST
  • Web page can be viewed as offering services via a REST API
    • GET request to read
    • POST to submit content

REST Design Guidelines

  • Use logical, not physical URIs
    • Physical: http://example.com/product/12345.html points to a file
    • Logical: http://example.com/product/12345 does not imply a file
  • Do not return large amounts of data
    • Comprehensive listing at http://example.com/product should paginate
  • Document well, keep updated, resist changing interface
    • Prettifying is unnecessary, machine-to-machine
  • Construct URIs needed for subsequent responses
    • Supply http://example.com/product/12345 instead of templated response
  • Comply with HTTP method semantics
    • For example, GET should not have side effects

API Keys

  • "Tokenization" to verify identity and prevent tampering
  • Same role as authentication
  • Helps service keep track of requests (e.g., for $)
  • Allows revocation via time-based or programmatic voiding
  • Public/Private key pairs for digital signing
  • Token is the "public key"


  • A URI to be invoked upon completion of a request to the API
POST /api.mysite.com/foo?action=fetch&callbackURI=http://testsite.com/processResults
  • Can also be a functional wrapper to be invoked upon returning
    • https://developer.github.com/v3/#json-p-callbacks


A JSON Response

"firstName": "Paul",
"lastName": "Allen",
"age": 62,
"address": {
	"streetAddress": "54 Oceanside Lane",
	"city": "Mercer Island",
	"state": "WA",
	"postalCode": "98040"
"phoneNumbers": [
		"type": "home",
		"number": "(206) 961-2355"
		"type": "office",
		"number": "(206) 451-1079 "
"children": []

The GitHub API: Basics

  • Documentation: https://developer.github.com/v3/
  • Allows keyless query:
    • curl -i https://api.github.com/users/machawk1/repos
    • Note: Private archives are not listed
  • Unauthenticated API access is rate limited
  • Authentication: curl -u "username" https://api.github.com

The GitHub API: Access

  1. Register App at GitHub.com to get client id and client secret.
  2. Authorize a user (GET request) with your client_id, requested scope, and redirect_uri
  3. Perform a POST with the returned code, client_id, and client_secret
    • client ID and secret obtained in GitHub's UI for your app
  4. Access token returned can be used for subsequent requests instead of client_*

Gravatar - a simpler API