The Differences between SOAP and REST APIs when handling User Data.

3 minute read time.

There are three types of web service in Sage CRM.

  1. SOAP
    1. The SOAP Web Services are the classic interfaces that adhere to the SOAP protocol specification.
  2. SData 1.1
    1. SData is a Sage standard that is used across many of Sage's products. It is a form of web service based on RESTful principles (Representational state transfer). The SData API is ReadOnly and returns XML.
  3. REST API (v1.0.0 beta)
    1. REST API grew out of the SDATA 2.0 specification but it has been taken sufficiently away from that starting point for us to redesignate this as our REST API. The REST is full CRUD and data is in JSON format. The REST API generally is simpler in detail than the SData specification and much broader in functionality

It is the SOAP and REST web services that provide a powerful basis for integration with 3rd party systems. This is especially true when we need to exchange data between systems scattered throughout the web as both these APIs allow a remote system to perform authenticated CRUD (Create, Read, Update & Delete) actions within Sage CRM.

There are differences in design and features between the SOAP and REST APIs. This is partly down to the REST API still being developed and extended. I pointed out in the article "Where next for the REST API?" that this is not a fixed and 'done' API like the existing COM, .NET, SOAP API and even SData API.

The SOAP API

For example when handling users the SOAP API allows for some user data to be queried from the system. The user entity is exposed to webservices and described in the WSDL. This is a very restricted understanding of the entity and not fields are exposed.

<complexType name="users">
<complexContent>
<extension base="typens:ewarebase">
<all>
<element name="createddate" minOccurs="0" maxOccurs="1" type="xsd:dateTime"/>
<element name="firstname" minOccurs="0" maxOccurs="1" type="xsd:string"/>
<element name="lastname" minOccurs="0" maxOccurs="1" type="xsd:string"/>
<element name="logon" minOccurs="0" maxOccurs="1" type="xsd:string"/>
<element name="updateddate" minOccurs="0" maxOccurs="1" type="xsd:dateTime"/>
<element name="userid" minOccurs="0" maxOccurs="1" type="xsd:int"/>
</all>
</extension>
</complexContent>
</complexType>


The SOAP The SOAP webservices are capable of Create, Read, Update, and Delete (CRUD) actions but the user table can only be inserted to using the AddResource action which adds a user that is not enabled for log on. The creation of users as resources prevents the nasty situation of where the web service program could run and create new users which then caused the total users in the system to exceed the number of allowed users in the license. This would then prevent any further logons. To recover from that the users would have to be either deleted, disabled or set as resources.

The REST API

The REST API because of it's roots within the SDATA API uses the same settings within metadata that determines whether a table is exposed to the API. The REST documentation lists those entities that have been tested and are officially supported for CRUD actions. The user table is not one of these.

Unlike the SOAP Web Services which uses the WSDL for schema discovery and that WSDSL is heavily restricted, the REST API uses the concept of a dynamically generated schema that can be interrogated and discovered.

In the REST API we use $prototypes to discover information about the system.

e.g.

http://localhost/sdata/crmj/sagecrm2/-/$prototypes

To find out information about an existing table or view exposed to SData we can use

http://localhost/sdata/crmj/sagecrm2/-/$prototypes/Company

The User table is NOT exposed by default to the REST API. If it was then it would become accessible for CRUD actions using the API and customers would face the same situation of inserting users that would then break the licensing.

In situations where only a listing of user information is required then it is possible to create expose a view to the SDATA and REST APIs.

Database views can be used to derive, calculate, join and transform data from multiple tables into a single source.

The image below shows the creation of a view in the context of the User entity. The view is called vSDataUserList and has been marked as available to SData.

NOTE:

This view then is available as an endpoint within SData.

http://localhost/sdata/crmj/sagecrm/-/vsdatauserlist/$schema

BUT to enable the view for the REST API the whole User table must be exposed to SDATA.

Using view is available to the REST API but it is not possible to request the prototype and will return an error "Resource kind does not exist".

The view should only be used for reading data.

e.g

http://sage020331/sdata/crmj/sagecrm2/-/vsdatauserlist?startindex=1&count=10

Parents Comment Children
No Data