Web services integration

This article gives a overview of the Web Services provided by the SAFE X3 platform.

The SAFE X3 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

SAFE X3 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 SAFE X3 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 Sage X3.

The applicative modules of Sage X3 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 Sage X3 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 Sage X3 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 Sage X3 Online.
  • OAuth 2 authentication: This is the only method available in Sage X3 Online, and the method of choice if you are already using an OAuth2 provider to authenticate users.

SData 2.0

The SAFE X3 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: