Introduzione agli Apex REST Web Services

Il protocollo REST (REpresentational State Transfer) rappresenta, ad oggi, uno dei protocolli internet più utilizzati quando si tratta di scrivere dei servizi web.

I principi su cui si basa il protocollo REST sono i seguenti:

  • Il sistema deve essere client-server – Esiste una risorsa che viene esposta nel web e un client che effettua le richieste a questa risorsa.
  • Stateless – Nessun contesto cliente viene salvato sul server. Ogni richiesta-risposta ha un contesto a sé.
  • Uniform interface – L’interfaccia di comunicazione tra client e server deve essere uniforme, in questo modo è possibile disaccoppiare le risorse dai client più facilmente.

Il protocollo REST utilizza i metodi http (get, post, put e delete) per inviare le richieste da client a server. Per saperne di più su REST qui il link Wikipedia.

Il protocollo REST in Salesforce

Come qualsiasi tecnologia moderna, anche Salesforce dispone di meccanismi Apex per poter creare delle REST-resource personalizzate.

Il REST Apex supporta due tipi di rappresentazione delle risorse: 

  • JSON
  • XML

La rappresentazione JSON è quella che viene utilizzata come default per il request/response body ed è il tipo viene indicato nell’header nella property “Content-Type”.

Una risorsa REST Apex dopo aver effettuato le elaborazioni necessarie può restituire i seguenti tipi:

  • Variabili primitive Apex
  • Oggetti sObject
  • Liste e mappe che contengono variabili primitive o degli oggetti sObject
  • Oggetti definiti da un’interfaccia a runtime che contiene a sua volta sObject o variabili primitive

Anatomia di una classe che espone una risorsa REST

I punti essenziali di una risorsa REST Apex sono i seguenti:

  • La classe deve essere annotata utilizzando la annotation @RestResource(urlMapping=’) e indicando nella property “urlMapping” l’url relativo a cui si potranno effettuare le richieste lato client
  • Ogni metodo che sarà esposto dovrà essere annotato utilizzando la annotation relativa al metodo http che si vuole utilizzare (@HttpPost, @HttpGet, @HttpPut, @HttpDelete)
  • Per avere accesso alle request/response si utilizzano le variabili di contesto: RestContext.request e RestContext.response.

Di seguito trovi lo snippet di codice contenente le tre basilari richieste di get, post e delete.

@RestResource(urlMapping='/Opportunity/*')
global with sharing class OpportunityResource{

    @HttpGet
    global static Opportunity doGet() {
        RestRequest req = RestContext.request;
        RestResponse res = RestContext.response;

        //nelle richieste get i parametri sono passati nell'url
        String opportunityId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
        Opportunity result = [SELECT Id, Name  FROM Opportunity WHERE Id = :opportunityId];
        return result;
    }

    @HttpPost
    global static String doPost(String name) {
        Opportunity opportunity = new Opportunity ();
        opportunity.Name = name;
        insert opportunity;
        return opportunity.Id;
    }
 
    @HttpDelete
    global static void doDelete() {
        RestRequest req = RestContext.request;
        RestResponse res = RestContext.response;
        String opportunityId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
        Opportunit opportunity = [SELECT Id FROM Account WHERE Id = :opportunityId ];
        delete opportunity;
    }
}

Normalmente le resource REST personalizzate contengono del codice molto più complesso, ma l’esempio di cui sopra contiene l’essenziale per capire come strutturare una Apex REST resource.

Restituire JSON personalizzati in una Apex REST Resource

Molto spesso, quando si decide di creare risorse REST personalizzate è perché si ha bisogno di inviare informazioni da più oggetti, o bisogna prima effettuare dei calcoli e poi inserire tutto nello stesso JSON.

Come possiamo creare delle risorse che ci consentano di personalizzare al massimo i dati interscambiati tra client e server? Fare questo è molto semplice, basta creare una classe all’interno della nostra risorsa REST e inserire all’interno tutte le variabili che vorremmo poi restituire al client che effettua la chiamata.

Attenzione! In questo caso bisogna scegliere con cura il nome delle variabili, perché esse verranno poi trasformate nelle “key” della coppia key-value del JSON restituito.

Ecco di seguito uno snippet di codice in cui si vede la creazione di una inner-class all’interno della risorsa REST principale e il JSON della risposta alla fine.

@RestResource(urlMapping='/MyTypeClass/*')
global with sharing class MyOwnTypeRestResource {
 
    @HttpPost
    global static MyTypeClass httpPost(MyTypeClass myClassType) {
        return myClassType;
    }
 
    global class MyTypeClass {
        global String string1;
        private String string2;
    }
    
}
Il Json di ritorno sarà il seguente:
{
    "myClassType" : {
                "string1" : "value for string1",
                "string2" : "value for string2",

            }
}

Complimenti, hai appena creato la tua prima risorsa REST Apex. Alla prossima guida!

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *