In the RESTful world, your operations are associated with a resource that is expressed via a Uniform Resource Identifier (URI). A resource can be a physical thing in your application, such as a Custom Object, or a conceptual thing. This is different from the Service layer design that drove the Apex API we looked at earlier, where operations are expressed by grouping them under functional areas of the application, which are then expressed by Apex Service classes and methods for each operation.
The Salesforce REST API uses objects to define physical resources the REST URI uses, allowing you to build a URI and use the various HTTP methods to perform the create, read, update, and delete operations. For example, to retrieve a record, you can issue the following request via the Force.com REST API sObject Resources too (https://developer.salesforce.com/docs/api-explorer):
In cases where you are exposing more business processes or task-orientated operations that are not data-centric, it can be difficult to decide what the resource name should actually be. So, it is worth taking the time to plan out and agree with the whole product team what the key REST resources are in the application and stick to them.
One operation that falls into this category in our FormulaForce package is the compliance report. This operates on a number of different Custom Object records to report compliance, such as the driver, car, and team. Should we define a URI that applies it to each of these physical resources individually, or create a new logical compliance resource?
I chose the latter in this chapter because it feels more extensible to do it this way, as it also leverages the compliance service in the application, which already supports adding new object types to the compliance checker. Thus, the REST API will support new object types without future changes to the API, as they are added to the compliance checker.
Salesforce dictates the initial parts of the URI used to define the resource and the developer gets to define the rest. For the compliance REST API, we will use this URI:
/services/apexrest/compliance
Once you package your Apex code implementing this REST API, you will find that the preceding URI needs to be qualified by your package namespace, so it will take on the format shown as follows from the point of view of Developer X, where fforce is my namespace. We will use this format of URI when we test the compliance REST API later in this chapter:
/services/apexrest/fforce/compliance