Order API Concepts¶

The term “Web API” generally refers to both sides of computer systems communicating over a network: the API services offered by a server, as well as the API offered by the client such as a web browser. The server-side portion of the web API is a programmatic interface to a defined request-response message system, which is typically referred to as the Web Service.

API Platform¶

The API environment we provide is a fully managed and 24/7 monitored platform. The platform is load balanced across different geographical data centres. This means that maintenance can be carried out without taking down the platform giving an API availability of 99.995%.

Whilst the API platform is fully resilient and managed, we leverage a third-party application called NetSuite® as an ERP. This creates a dependency, which can affect the overall availability of the service to resellers during times of maintenance.

You will be notified via the API if an error occurs due to NetSuite® maintenance. Normally this error would only occur outside of UK trading hours, however with customers all over the world using this API, it may present itself from time-to-time. Details on how to handle this error should it occur, are covered in the error handling section. We will notify youin advance of any scheduled NetSuite® maintenance to minimise any impact to the service – make sure that your contact information with us is up to date.

Synchronous API¶

The API will provide a real-time response to submissions made and is therefore synchronous. Your code must wait for a response to every request. The time it takes for a response will vary depending on the requests that are made and the downstream services that are required to validate and process the request.

Although responses are typically returned very quickly, it is recommended that the connection is left open for up to 180 seconds to capture the response.

WSDL¶

Web Services Description Language (WSDL) is an XML-based interface definition language that is used for describing the functionality offered by a web service. The WSDL contains almost the complete picture of everything that is required to integrate with a service.

The WSDL defines every aspect of the Simple Object Access Protocol (SOAP) message. It is even able to define whether any element or attribute is allowed to appear multiple times, if it is required or optional, and can even dictate a specific order the elements must appear in.

Although technically a WSDL is not required to interface with a SOAP interface, a developer only needs to be given the WSDL to generate method stubs with appropriate parameters in almost any language from that WSDL. Many test tools on the market work in the same way – a tester provides a URL to a WSDL, and the tools generate all the calls with sample parameters for all the available methods.

To make this process even easier for you, we can provide sample code in Java to get a you up and running on the Nuvias UC staging environment.

The WSDL can be seen as a contract between the provider and the reseller of the service.

SOAP¶

Simple Object Access Protocol (SOAP) has been the dominant approach to web service interfaces for a long time and is aimed at Enterprise M2M solutions. SOAP is a mature protocol with a complete specification, which is designed to expose individual operations – or pieces of operations – as web services. One of the most important characteristics of SOAP is that it uses XML to define the content of its messaging and together with schemas, defines a very strongly typed messaging framework.

Every operation the service provides is explicitly defined, along with the XML structure of the request and response for that operation. Each input parameter is similarly defined and bound to a type: for example, an integer, a string, or some other complex object.

SOAP is good for formal contracts between the API and your code, since it enforces the use of formal contracts by using WSDL.

Transport¶

SOAP is usually agnostic of the underlying transport protocol, however for this API the transport protocol is HTTPS which ensures that the traffic being sent is encrypted end to end.

Certificate¶

We use a certificate in the API to support two-way authentication and message signing.

You will need to generate an X.509 that you will use to sign all SOAP messages and provide us with the public key certificate, which will be used to authenticate the message.

We don’t require your certificate to be signed by an official Certificate Authority and a self-signed certificate is perfectly acceptable, but the private key must be kept secure, as anyone with it will be able to submit orders in the your name. We accept a valid and correctly signed order as a contractually binding order in accordance with our terms and conditions.

For example, the Test Reseller certificate included within the Sample code has the following values.

Subject: C=UK, ST=England, L=London, O=inCloudOne Ltd, OU=Testing, CN=Test Reseller

Certificates that do not meet the stipulations above will be rejected.

The reseller should provide the certificate in PEM format unless there is a compelling reason not to. In PEM format the public key certificate should begin with the following line:

-----BEGIN CERTIFICATE——