Thoughts on RESTful API Design

Lessons learnt from designing the Red Hat Enterprise Virtualization API

Author: Geert Jansen <gjansen@redhat.com>

Date: November 15th, 2012

This work is licensed under a Creative Commons Attribution 3.0 Unported License.

The source of this document can be found on github.

• Introduction
• The Job of the API Designer
  • The Application
  • The API Code
  • The Client
• Resources
  • Resource Data
  • Representations
  • Content-Types
• URLs
  • Entry Point
  • URL Structure
  • Relative vs Absolute
  • URL Templates
  • Variants
• Methods
  • Standard Methods
  • Actions
  • PATCH vs PUT
  • Link Headers
  • Asynchronous Requests
  • Ranges / Pagination
  • Notifications
• Relationships
  • Standard Structural Relationships
  • Modeling Semantic Relationships
• Forms
  • Type Definition
  • Service Definition
  • Using Forms to Guide Input
  • Linking to Forms
• Miscellaneous Topics
  • Offline Help