1. Integration API Guide
  2. Web Services and REST Overview

Web Services and REST Overview

This section is intended to give a high level overview of web services, how they work, and how customers use them. Web services are a common method by which machines are able to passing data, files, or invoking a process over the internet using the HTTP protocol. The two main flavors of web services are SOAP (Simple Object Access Protocol) and REST (Representational State Transfer). This section will focus primarily on REST (a service based on REST is called a RESTful service) as it's the web service method used by Oracle WMS Cloud.

Objective of Web Services
  • The main object of web services is to provide a window to a resource on a server
  • A resource can be a document, picture, video, web page, API, or anything that can be represented in a computer system
Why REST Web Services?
  • RESTful services are lightweight, maintainable, and scaleable (all important things for a cloud application)
How Do Web Services Utilize HTTP?
  • HTTP is the underlying protocol used by web services
  • This is the same protocol you just used to request this web page (a resource!) in your browser
  • HTTP provides mechanisms to handle the requests and responses to RESTful services
  • This includes transferring data and/or files
  • The Client/Service/Server Relationship
  • A client is the system connecting to and making a request to a service hosted on a server
  • The server processes the request, returns a response to the client, and closes the connection
HTTP Messages
  • Clients and services talk to each other via messages
  • HTTP messages follow a request and response cycle; each request by the client requires a response from the server
  • It's possible to not get a response from the server. That typically means there was an issue with the server's execution of the request.
  • Requests to a service and responses from a service are both structured messages
  • The actual message is just a series of lines of plain text (see Request Example below)
Request structure

An HTTP request is really nothing more than several lines of text that tell a client about the request it needs to execute.

Here we will discuss the components of a request and then walk through an example using the Google Chrome extension, POSTman.

  • Verb
  • An HTTP method that defines the action of the request
  • Examples: GET, POST, PUT, DELETE, ...
  • WMS primarily requires clients to POST to our resources
  • Some clients and Jitterbit may utilize GET
  • URI (Uniform Resource Identifier)
  • A URI is a resource on a server that can be accessed by a service
  • The most common form of URI is a URL (Uniform Resource Locator)
  • A URL specifies both the primary access mechanism and network location
  • In simple terms a URL identifies the network and location of the resource being accessed
  • Example: http://example.org/wiki/Main_Page
  • This URL refers to the resource /wiki/Main_Page that is obtained via HTTP from a network whose domain name is example.org
  • HTTP Version
  • Current version is "HTTP v1.1"
  • Request Header
  • Contains request metadata in a collection of key-value pairs
  • In general, this is information about the request, the requesting client, authorization, and the format of any data in the request body
  • The most important header keys for WMS's purposes are:
  • Authorization - An encrypted username/password combination that may be required to access the service
  • Content-Type - Defines the format and possibly the encoding (charset) of the data in the request body for POST requests
  • The format is known as a MIME Type
  • Important POST MIME Types:
  • application/x-www-form-urlencoded
  • Alphanumeric data is encoded (convert legal non-ASCII characters to a representation using allowed characters) and sent in key-value pairs in the request body
  • Any illegal characters, like ñ, are encoded to an ASCII hex representation like "%XX" and then decoded back after transmission
  • Example: If you have one field "Name" with a value of "Mary" and another field "Gender" set to "Male", it would be represented as: Name=Mary&Gender=Male
  • multipart/form-data
  • The data is sent in key-value pairs in the request body in multiple parts
  • Typically used for transmitting files (binary data)
  • Good for transmitting large amounts of data
  • application/xml
  • The content of the request body is XML
  • Request Body
  • The actual content (data) of the message
  • Format (and possibly encoding) is determined by the Content-Type header
  • Key-value pairs are represented in the format: key1=value1&key2=value2&key3=value3...
  • key/value are separated by "="
  • pairs are separated by "&"
  • However, if for example the Content-Type is set to "application/xml" there would be no key-value pairs, just an XML message