Introduction
Force.com has released its REST API as a lightweight channel to access data on the platform(cloud). The basic framework remains the same for REST based services. Request and response can flow in XML or JSON format. The beauty of RESTful service is that its very lightweight and easy to use as compared to SOAP based services.
We will quickly jump over to code that explains how to create a RESTful service on Force.com using Apex.
Diving deep into code:
- We need a class with keyword "@RestResource" to signify the class responsible for handling HTTP requests and act as REST based web service. Make sure the class has global access specifier.
- The urlMapping property allows us to set path where the service will be available. This is process of setting up the endpoint for service. Example: https://
.salesforce.com/services/apexrest/showAccounts - Include @HttpGet keyword before method name for denoting a method to respond on a HTTP GET request; include @HttpPost keyword before method name for denoting a method to respond on a HTTP POST; include @HttpDelete keyword before method name for denoting a method to respond on a HTTP DELETE. Similarly for HTTP PUT and PATCH methods
- Make sure that methods responsible for handling HTTP requests have global access specifier and static keyword with them.
- The awesome feature is that you can set return type as primitive type, standard objects or custom objects within your salesforce.com development environment. In this example the list of accounts will be returned to client invoking the service.
- In order to pass parameters to service, you can use RestRequest object in a method. example:
- The limitation here is that within a RESTful apex class you can have only one method with @HttpGet keyword.i.e. one method can respond to HTTP GET requests in this class or URL path. same applies for @HttpPost, @HttpDelete, @HttpPut, @HttpPatch
Live Action:
In order to consume this service we need a client that can make HTTP calls to the respective endpoint where service is listening for requests. You can write your client using cURL, java, c, c++,etc
The main step to consume this service is to go through OAuth 2.0 authorization flow to access the resources protected by Force.com platform.
For ease I will use Advanced REST client for Chrome to demo this:
Set Endpoint:
Set body :
grant_type=password&client_id=your_clientid_here&client_secret=your_client_secret_here&username=your_username&password=your_password_here *Append your security token if your IP, from where you are invoking the serviceis not in IP whitelist.
Response you get:
{"id": "https://.salesforce.com/id/00DO00000004qZHMAY/00590000000G0keAAC ","issued_at": "1338103748715","instance_url": " ","signature": "N++wJCOHvBdyxR9TTa8VpLkRdBGODgvf5VLmgNhdFHQ=","access_token":"00DO00000004qZH!ARYAQD9cEL5NSrHrjHFwuQcSh5ktdbGLobvF8NiasAuYwZ7sm80G48Mt9sdCPsT42_Ff69ieOe9dozP_BYEASuvA_BTPwgP_"}
Screenshot:
I will make a HTTP POST request to endpoint:https://cs5.salesforce.com/services/oauth2/token*When trying this make sure you replace cs5 with appropriate salesforce.com instance
Set body :
grant_type=password&client_id=your_clientid_here&client_secret=your_client_secret_here&
Response you get:
{"id": "https://
Screenshot:
Keep this access_token as you need it to invoke the RESTful service.
Invoking the service:
Now we are ready to invoke the service we just created.
Set Endpoint:
I will make a HTTP GET request to endpoint(since method is defined with keyword @HttpGet):
https://cs5.salesforce.com/services/apexrest/showAccounts
*When trying this make sure you replace cs5 with appropriate salesforce.com instance
Set Header:
Authorization: OAuth 00DO00000004qZH!ARYAQH.xMKtnnchDH6zTYvkMMYRLIflZgGiZ74EXgTsRyowAUwyk5Xcc1ZoH3C.sZ4oMnsfioPFbKdhlTSdI02hjQPF2FX_0
Response you get:
[
{
"attributes": {
"type": "Account",
"url": "/services/data/v25.0/sobjects/Account/001O00000056mOkIAI"
},
"Name": "Google",
"Id": "001O00000056mOkIAI"
},
{
"attributes": {
"type": "Account",
"url": "/services/data/v25.0/sobjects/Account/001O0000003oCQnIAM"
},
"Name": "Microsoft",
"Id": "001O0000003oCQnIAM"
},
{
"attributes": {
"type": "Account",
"url": "/services/data/v25.0/sobjects/Account/001O00000056mOpIAI"
},
"Name": "Facebook",
"Id": "001O00000056mOpIAI"
},
{
"attributes": {
"type": "Account",
"url": "/services/data/v25.0/sobjects/Account/001O00000056mO2IAI"
},
"Name": "FourSquare",
"Id": "001O00000056mO2IAI"
}
]
screenshot:
This shows the list of accounts in your environment.
I hope this blog help you understand and create RESTful services in Force.com.
Cheers !