CMSC389L

APIs

APIs: Overview

• An application programming interface (API) is a set of clearly defined methods of communication between various software components.
  • Can build apps as interconnected modules.
• Expose resources as building blocks for more complex applications
  • Hidden implementation details

APIs: SaaS Businesses

• APIs are fundamental to how many SaaS companies work
  • The API is their business model

APIs: Other Examples

• You've built APIs before:
  • Java classes
    • public methods vs. private implementation details
• You've used them before:
  • java.util
  • Websites
• Many varieties of APIs:
  • Databases
  • GUIs!
  • etc.

APIs: HTTP Protocol

• Web-based APIs commonly communicate via HTTP
• HTTP: HyperText Transfer Protocol
  • Stateless, application-layer data transmission protocol
  • ​Foundation of data communication on the modern web
• Important HTTP components:
  • URLs
  • Verbs
  • Status Codes
  • Headers

HTTP: Urls

From umd.io:

  ​http://api.umd.io/v0/courses?dept_id=CMSC,BMGT&credits<2

HTTP: Verbs

• URLs specify what resource to interact with
  • Verbs specify how to interact with the resource
• Verbs:
  • GET: fetch an existing resources
    • ​special: browsers expect idempotency!
  • POST: create a new resource.
  • PUT: update an existing resource
  • DELETE: delete an existing resource
  • Others: HEAD, TRACE, OPTIONS, PATCH, ...

HTTP: Verb Examples

• GET
    http://api.umd.io/v0/courses?dept_id=CMSC,BMGT&credits<2​

HTTP: Verb Examples

$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
    -d "Body=Jenny%20please%3F%21%20I%20love%20you%20<3" \
    -d "To=%2B15558675309" \
    -d "From=%2B14158141829" \
    -d "MediaUrl=http://www.example.com/hearts.png" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

HTTP: Status Codes

• Status codes instruct the client on how to interpret a response.
  • 3 digit number (100 - 599)
  • A canonical message is associated with each number.
• Status code numbers are split into categories
  • 100 - 199: Informational
  • 200 - 299: Successful (200: "OK")
  • 300 - 399: Redirect
    • 301: "Moved", 304: "Not Modified"
  • 400 - 499: Client error
    • ​400: "Bad Request", 401: "Unauthorized"
      403: "Forbidden", 429: "Too Many Requests", etc.
  • 500 - 599: Server error (​500: "Internal Error")

HTTP: Headers

• Headers specify metadata in request and response messages.
• Examples of common headers:
  • Cookie: $Cart=[4357,3840]; User=1234;
  • Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
  • Content-Type: application/json
  • Content-Encoding: gzip
  • Content-Length: 348
  • Expires: Thu, 01 Dec 1994 16:00:00 GMT

APIs: REST

• Many different architectural styles for creating APIs: SOAP, RPC, REST, etc.
• REpresentational State Transfer (REST):
  • series of constraints that improve scalability of the web
  • Resources are expressed with URL ids
    • tickets -> GET /tickets
    • ticket price -> GET /tickets/:id/price
    • etc.
  • Requires statelessness, caching, separation of concerns, invisible intermediaries (f.e. load balancers), ...

APIs: Pragmatic API Design

• Pragmatic API design:
  • Easy to use APIs -- they should be guessable
• Some basics:
  • Resources are nouns (/tickets, /courses, /courses/12, ...)
  • Consistent naming scheme, always plural nouns,
  • Use versioning, and aim for backwards-compatibility
  • Apply filters with query parameters
  • Use common generic parameter names
    • /tickets?sort=-priority
  • Incorporate an API review process
  • Pretty print by default
  • Avoid abbreviations
  • Choose reasonable defaults, minimize boilerplate

APIs: JSON vs. XML

APIs: Pragmatic API Design

• Example: Stripe
  • Traditional v1/v2/v3-style versioning
    • Upgrading between major versions is hard for developers
    • Supporting old versions slows development
  • Stripe uses daily versioning
    • API upgrades are expressed as transformations
    • Benefits:
      • Developers can upgrade any time
      • Deprecations are rare, rather than regular
      • Streamlined API development process
• Read more: stripe.com/blog/api-versioning

APIs Worksheet

API Demo

API Gateway: What is it?

• Managed infrastructure used to build out web-based REST APIs.
• You'd want an API server to be highly available, secure, and scalable.
  • without the time-consuming implementation
  • Instead, focus on the business logic (the API itself)

API Gateway: What is it?

• API Gateway allows you to configure your API and redirect requests within your AWS infrastructure.

API Gateway: Benefits

• Benefits:
  • Built-in Throttling (429 Error Codes)
  • Managed Cache to store API responses
  • Security
  • Versioning and A/B Testing
  • Automatic CloudFront integration (DDoS protection, reduced latency, etc.)
  • SDK Generation (mobile, JS, server, etc.)
  • API Mocking
  • Stages (Dev, Staging, Prod, etc.)
  • Automatic Timeouts
  • Data Transformations
  • Integrated Usage Plans (Sell your API!)
  • Centralized logging and metrics
  • ...

API Gateway: AWS Support

• Use it with:
  • Lambda
  • EC2
  • DynamoDB
  • S3
  • Elastic Beanstalk
  • ...
  • Any web URL, including other APIs
    • Proxy APIs

API Gateway: Services

API Gateway Pricing

Three factors in the cost of using API Gateway:

• # of API calls: $3.50 / 1M API calls
• Data Transfer Out: $0.09 / GB
• Optional Caching

 

Free Tier: 1M API calls / month

 

API Gateway Demo