REST Design Concerns

• Less Requests, More data; one of the core RESTful API design paradigms is the concept of less API requests should be made with less data yielding larger more complete responses. The cost associated to a transaction is defined primarily by the transport layer data and not the payload of a request, thus less is more.
  • To this extent, when performing a PUT on a resource, it is in the best interest of the API to allow edits for all editable properties. This will allow a Consumer to keep costs lower when they need to edit a MMY AND a VIN for instance. 
• Idempotence; This term has caused the most confusion. A core Software Design and critical API concept an API call is considered idempotent if subsequent calls of that API yield the same results and the same state for that resource. 
  • For a proper REST API design, GET and POST requests can never be idempotent, PUT and DELETE requests should always be idempotent
  • Enforcing Idempotence for PUTs and DELETEs ensures a consumer knows what they are going to get always. No assumptions need to be made about the resultant resources state and the Consumer can call the method confident that what they gave is what the entity is.
• Multi-Consumer API Solutions cannot enforce an accurate state representation of a resource without enforcing Idempotency. Simply put, state of a resource is not what a consumer expects it to be without Idempotency.
• Limiting Network based Transient Faults; When a Consumer experiences a network connection issue, or a component within the Connected Car solution experiences network connection issues while a PUT or DELETE is being processed, the Consumer will receive either a 400 or 500 series error. That resource is now considered Transient and confidence the Entity has been modified is non-existent
  • Even with the most solid design High Available system, a network based transient fault is not just possible, but inevitable.
  • Enforcing Idempotency on our PUTs and DELETEs will allow a Consumer to simply retry the request knowing that the resultant resource is exactly what they wanted, regardless of the previous API call's state.
• Data Synchronization and REST Resource Accessibility; A REST API is more in tune with a Check-out/Check-in model than it is to an RPC API model.
  • A Consumer is expected to maintain a synchronized data model via GET requests & Synchronization Task Calls (Multi Vehicle Search and Account Synchronization for example) before performing a subsequent modification. AKA Check-Out that resource, modify that resource and Check it In.
  • In RPC, the inverse is expected, a Consumer would submit what they would like the model to be and the API will tell the Consumer what the resultant resource will be.
  • The latter model removes control from the Consumer and can limit their ability to accurately consume the APIs resource. Simply put, the consumer may never truly know what the resource will be until AFTER the modification has been made and committed.
  • In addition, the former model creates a more performant API. The responsibilities are levied on the Consumer as opposed to the API, thus reducing impacts to other consumers, reducing processing time and simplifying the APIs business logic. For Connected Car, this can be considered a priority.