RESTful design rules promote best practices for building scalable APIs. The rules encourage contract-first design, establish standards, and reduce support costs. Key rules include using a uniform interface with URIs to identify resources, caching to improve performance, and making services stateless. Resources should have self-descriptive representations and link to related resources to allow navigation without hard-coded URIs. Common HTTP methods like GET, POST, PUT and DELETE should map to standard CRUD operations, and status codes indicate request outcomes.

1. RESTful Design Rules

2. Why? – adds value
• Encourages a Contract-First API service
• Rules help design for scalable services
• Establishes a design standard and language
• Rules promotes a “crisp”API making happy clients,
reducing Support costs and sells the API (Netflix,
Google, Github)
• Sources : Apache project, Roy Fielding thesis
• “Rest API Design Rule Book” - Mark Masse
(O'Reilly Pub)

3. Web Architecture Scalability
Constraints
• Client-Server: must play distinct roles
• Uniform Interface: standard interaction
between client and server components
• Cache : reduce latency, improve availability.
Client or server
• Stateless: resource at server has no state. Only
client has conversational state

4. Uniform Interface
• Identify service resources with an address: URI
• Resource representation – resource returns
different representations to different clients
• Self descriptive – desired resource state
reflected in request and current state in
response. An update is successful or not
• Links(HATEOAS) – current state defines links to
related allowed links, may depend on client

5. Questions
• How do I design for self-descriptive messages?
• REST models state – how do I model this?
• What URI name shall I use for CRUD services?
• What URI name shall I use for non-CRUD
services?
• What HTTP response status codes to use for
use cases?

6. REST Modeling
• HTTP methods for CRUD or non-CRUD services
• Document/Resource – object, record : animal
• Collection resource – many related objects:
animals (=database)
• Store resource – many unrelated documents
• Controller resource – process resource
• Idempotent – side affect free
• URI path – hierarchy of resources; /cats/felix

7. HTTP Method-Service Map
• GET(SELECT) – Retrieve document(s)
• POST(CREATE) – Create a new resource in a
collection
• POST(PROCESS) – Perform non-CRUD process
• PUT(UPDATE) – Update resource
• DELETE(DELETE) – Delete resource
• PATCH(UPDATE) – Update with changes
• HEAD – Get metadata or “ping” resource
• OPTIONS – Get resource’s “Allowed” URI links

8. Recommended Status Codes
• 200 OK – [GET]
• 201 CREATED – [POST/PUT/PATCH]
• 202 ACCEPTED – [POST], async action
• 204 NO CONTENT – [DELETE]
• 400 BAD REQUEST – [*]
• 404 NOT FOUND – [*]
• 500 INTERNAL SERVER ERROR – [*]

9. Expected URI & Responses
• GET /collection : Return list of resources
• GET /collection/resourceId: Return a resource
• POST /collection : Create resource, return Id
• PUT /collection/resourceId : Update resource
• DELETE /collection/resource : Return empty
body
• PATCH /collection/resource : Return updated
resource

10. State REL links - HATEOAS
{
// fields …
“links” : {
“self” : {
“href” : http://api.project.company.org/departments/1/employee/100
},
“parent” : {
“href” : http://api.project.company.org/departments/1
},
“outOfOffice” : { // Out of office state change
“href” :
http://api.project.company.org/departments/1/employee/100/outOfOffice
“method”:”POST”
},
}
}

11. HATEOAS
• Hypermedia as the engine of state
• Decouples client and server. No hard coded
URIs in client
• REST service controls state transitions through
available links
• Available Open Source libraries to generate
links

12. Pagination
• Use filter query parameters &page=1
• Normal GET resource must not use query
parameters
• Filter on start, end page and page size
• Returned HATEOAS links must define href links
with rel elements for = “next”,
“previous”,”first” and “last”

13. REST Rules
• Separator (/) indicates a hierarchy relationship
• Trailing slash (/) must not be included in URIs
• Singular noun for document names
• Plural noun for collection and store names
• Verb or verb phrase for controller names
• Exclude file extensions in URIs (no .xml etc)
• CRUD function names should not be used in
URIs; not /deleteUser/1234 but /user/1234