Writing URI

Resource Name

• Resources names are ALWAYS nouns in plural
  • Example: /case-files, /complaints, etc.
• Concatenating resource names is with hyphen(dash) ”-”:
  • Example case-files, person-associations, etc
• Resource name should be intuitive
• URI should always represent resource structure only

Inserting New Record

• For inserting new record we use POST method with same resource name:
  • Example: POST: /case-files and case file record is in the body
• Inserting sub resources with parent:
  • Example: POST: /case-files/103/tasks and in the body is task record
• Uploading files:
  • Example: POST: /case-files/103/attachments/dir1/dir2/dirN and multipart in the body

 Updating Existing Record

• For updating existing record we use PUT method with same resource name with suffix /{ID} and record in the body
• Example: PUT: /case-files/123 – case file record is in the body
• Example: PUT: /case-files/123/activate – empty body
• For updating child objects we use parent resource as prefix:
  • Example: PUT: /case-files/123/tasks/123 – updated task in body
• For updating multiple records should we use body
  • Example: PUT: /case-files – records in the body
• Partial updates should be used with PATCH
  • Example: PATCH: /case-files/123 – in the body fields which need to be updated
  • Example for multiple records: PATCH: /case-files/123,124,125 – in the body fields which need to be updated to all listed records? Same problem with versioning.

 Deleting Existing Record

• For deleting existing record we use DELETE method with same resource name with suffix /{ID}
  • Example: DELETE: /case-files/123
• For deleting child objects we use parent resource as prefix:
  • Example: DELETE: /case-files/123/tasks/123
• For deleting multiple records should we use URI or body?
  • Example: DELETE: /case-files/123,124,125,126 – with empty body
• What if we have record versioning?
  • Example: DELETE: /case-files/132/attachments/dir1 – this should delete all files in dir1