API Architecture
The OMN REST APIs are REST over HTTP-like APIs that follow the REST architectural style and guiding constraints. Clients can communicate with the APIs via HTTPS. The APIs support JSON and XML as request and response format.
REST Style and guiding constraints
Client-Server
The user interface (client) concerns are separated from the server (OMN API) concerns (separation of concerns), which means both components can evolve independently.
Statelessness
Servers don’t maintain client state, clients manage their own application state. The client’s requests to the server contain all the information required to process them.
Cacheable
Responses as marked as cacheable or not. Systems and clients can cache responses when convenient to improve performance. They also dispose of non-cacheable information, so no client uses stale data.
Layered system
Clients cannot see beyond server layer. For example if a proxy or load balancer is placed between the client and server. This confined scope allows OMN server to easily add load-balancers and proxies to improve authentication security or performance.
Uniform interface
OMN REST services provide data as resources, with a consistent namespace.
-
The resources requested are identifiable and separate from the representations sent to the client.
-
Resources can be manipulated by the client via the representation they receive because it contains enough information to do so.
-
Self-describing messages returned to the client contain enough information to describe the way the client processes them.
-
Hypertext/Hypermedia, i.e. after accessing a resource, the client should be able to use hyperlinks to find all currently available executable actions.
Supported Request and Response Formats
OMN API supports JSON and XML as request or response format.
JSON requests are supported in UTF-8 and are the default.
XML requests are supported in UTF-8 and UTF-16. XML responses are provided in UTF-8.
Use the HTTP ACCEPT header to specify either JSON or XML.
Cross-Origin Resource Sharing (CORS)
Problem: Current web browsers enforce that clients can only make requests to a resource whose origin matches the client’s URL. The client URL protocol, port, and hostname should all match the requested server. So how can clients use resources from external 3rd parties (for example from external APIs)?
Cross-Origin Resource Sharing (CORS) is a mechanism for integrating applications. It allows client web applications to request resources from origins other than their own (another domain outside the domain from which the first resource was served). This enables client applications to reference 3rd party API resources.