This article is a summary of my notes about the Lightning Platform REST API that I have made while studying for the Integration Architect exam.
Lightning Platform REST API
The REST API is the API generally recommended for creating, searching and manipulating data. It provides flexible and scalable programmatic access to your integrations. It works by sending an HTTP request to endpoints in Salesforce.
What is Rest?
REST stands for Representational State Transfer. REST is a style of software architecture made up of principles that describe how network resources are accessed and described.
Why REST and not SOAP?
Both have their place in Salesforce integrations. SOAP is a prescribed protocol which has specific requirements like XML, security and transaction compliance and messaging. These all make SOAP a slower and heavier protocol compared to REST.
What is HTTP or HTTP Requests?
HTTP stands for Hypertext Transfer Protocol and is used to structure requests and responses over the internet. HTTP requires data to be transferred from one point to another over the network. …. HTTP is the command language that the devices on both sides of the connection must follow in order to communicate.
Source Codecademy: https://www.codecademy.com/articles/http-requests
The HTTP requests enable you to access and carry out actions on different resources (such as field data, field metadata, records, etc). The information delivered can be in the format of JSON, HTML, XML, among others.
There are 4 HTTP “verbs” used in HTTP requests to interact with resources over the REST API:
- GET: retrieve a single resource or collection of resources
- POST: create a new resource (such as a record)
- PUT: update a specific resource. For this you will need to know the Id of the resource.
- DELETE: remove a specific resource. Again, the Id will need to be known.
These allow you to determine available API versions and access limits as well as retrieve object metadata, carry out CRUD (Creat, Read, Update, Delete) operations on records and query data.
Each HTTP Request has the following methods:
- URI: This is a Uniform Resource Identifier. It is not a misspelling of URL which is a Uniform Resource Locator. In the HTTP Request this is the path to a resource in Salesforce. A URI typically looks like this:
https://domainofchoice.my.salesforce.com/services/data/vXX.X/resource/
The domainofchoice being the My Domain applied to the Salesforce Org and vXX.X being the API version you have chosen to use. - HTTP method: Those HTTP verbs mentioned above.
- Headers: Headers contain formats you will accept for the response body, and other parameters and options such as the content type of the request body attached (application/json or application/xml) and authorisation elements such as OAuth 2.0 access token.
- Request Body: This is the data bytes transmitted in an HTTP transaction message. However you will not have a request body in a GET HTTP Request. This makes sense – you are asking for / retrieving a resource.
A short note about HTTP Request Headers. Headers and parameters contain important identifier information as to the request’s metadata, authorisation, the URI, caching, cookies, etc. They can also contain Compression Headers and Conditional Requests.
- Compression Headers compress the REST API request or response to reduce bandwidth of the request at the expense of processing power.
- Conditional Requests can validate resources before accessing them.
There are two types of validations:
- Strong (If-Match or If-None-Match) where an exact pre-condition must be met before accessing the endpoint resource, or
- Weak (If-Modified-Since or If-Unmodified-Since) where the validation does not need to be identical to the validation.
What is REST API Architecture?
This is a term I came across a lot in my studying on API’s for integrations. It essentially means that the Salesforce REST API follows standard RESTful principles and characteristics. So there will be a client-server (which holds the client applications seeking to access the REST API).
They must be stateless which means the requests are complete and separate from where they originated from. When reading the request from a client-server, there should be no requirement to look back at that server for information. All resources should be accessible with a uniform / generic interface over the APIs. This is not a complete list and this part of the REST API guide sets out REST API Architecture.
Authorisation
To access REST API resources the Client application must be authorised as a safe visitor. We use Connected Apps and OAuth 2.0 authorisation flows to do this.
Connected Apps:
See my fuller notes on Connected Apps in this blog item: Identity and Access Notes: Connected Apps
What is OAuth 2.0?
When a User wants to access protected resources in the API, they use a client application to access the API (the Resource Server’s API). At this point the client application is not authorised and access the API anonymously. The Resource Server does not know who the client application is and so redirects the User to the Authorisation server. The Authorisation Server checks the identity of the client application and, if verified, grants the user permission by returning an access token. The access token contains the information required to allow the client application to access the Resource Server. The Resource Server receives this token and uses the information in the access token to determine what access the client application can have for the User. It does this by checking the signature and reading the payload.
OAuth Authorisation flows
Each OAuth authorisation flow is different, but does contain three key steps. Note: see a whole section on OAuth Authorisation Flows in Salesforce Help.
- A connected app on behalf of the client requests access to the REST API resource – this is the initiating step.
- An authorising server grants access tokens to the connected app – this is the response.
- The access tokens get validated by the resource server and approve access to the protected REST API resource.
Please see additional notes on API’s and Connectors in this series of notes and also always double check with current Salesforce documentation.