Web services integration

This article gives a overview of the Web Services provided by the EMP platform.
The EMP platform is fundamentally a service-oriented platform. The applicative
modules expose either a Web API (RESTful services) or more traditional SOAP web
services that you can call from any language.
This article gives an overview of the Web Services supported by the platform and it
gives pointers to articles that illustrate the various Web Services scenarios through
small examples.

Web API and SOAP services

EMP Web Services come in two flavors:
 Web API: these Web Services follow the RESTful style. Every resource of the
application (a supplier, a customer, a sales order, a product, a user, etc.) is identified
by a simple URL. Through this URL, an external component can read the data of a
resource, update it or even (if allowed by the business logic) delete it. An external
component can also query a list of resources (a list of customers for example), with an
optional criteria, and can as well invoke service operations on resources or list thereof.
This Web API is available on every representation which has been configured in the
EMP dictionaries.
 SOAP Web Services: these web services use the traditional SOAP protocol to
access the application data. Unlike the Web API, the service is accessed through a
single service URL and the operation to perform is described by a special XML payload
which is posted to the service URL. These SOAP web services are available on the
main classic functions of Enterprise Management.
The applicative modules of Enterprise Management are undergoing a progressive
upgrade from a classic implementation based on masks, screens and windows to a
new service oriented implementation based on classes and representations. So the
flavor of web service that you should use for a given applicative module depends on
whether the module has been upgraded or not. The general rule is the following:
 The Web API can be used to read data from all modules, as Enterprise
Management is already providing read-only representations on all resources.
 The Web API should be used to update data from modules that have been
upgraded. Resources that you access with the mobile client can be read and modified
though the Web API.
 The SOAP API is available on modules that haven't yet been upgraded. These
are the modules that you access via the classic interface in the browser. The SOAP
API supports read and update operations.
SOAP services have been available since V6 and have their own documentation. This
guide does not give detailed documentation on them. Instead, it focuses on the Web
API and on common mechanisms such as authentication.

Authentication
Web Service calls can be authenticated with a username and password (basic
authentication), with a certificate or with OAuth2 tokens. The following articles describe
how to use these authentication methods:
 Basic authentication: This method is the simplest one but it is difficult to secure
because the web service client must provide (and thus store) a password. This method
is only available on-premise; it is not supported by Enterprise Management Online.
 Certificate authentication: This method will usually be the method of choice for
on-premise deployments. It allows you to secure web service calls without having to
integrate with an external OAuth2 provider. This method is not supported by Enterprise
Management Online.
 OAuth 2 authentication: This is the only method available in Enterprise
Management Online, and the method of choice if you are already using an OAuth2
provider to authenticate users.

SData 2.0
The EMP Web API is based on SData 2.0, a RESTful protocol specification published
by Sage.
There are a few differences between this Web API and the SData protocol. They are
summarized in this article.

Testing interactively
Web API calls are usually issued by programs but, as they are just HTTP requests they
can also be tested interactively, directly in the browser, or better, with a tool
like Postman.
If you test the URL with your browser you will be redirected to the login page first. After
login you will get the result of your query.
If you test with a tool like Postman you will need to add an HTTP `Autorization` header
to your request. An easy way to start is to configure [basic authentication](../integration-
guide/ws-basic-authentication.md). If you have installed node.js on your machine you
can obtain this header with:

CODECODE CODEsh

node -e "console.log('Basic ' + new Buffer('user:password').toString('base64'))"

where `user` and `password` are the user and password that you have configured for
web services. This will print something like:

Basic dXNlcjpwYXNzd29yZA==

Using the Web API

The following articles cover various usage scenarios around the Web API:
 Querying a list of resources
 Reading the details of a single resource
 Creating a resource
 Updating an existing resource
 Deleting a resource

Links
 EMP Integration Guide
 RESTful Web API
 SOAP Web Services
 SData 2.0 Specification