The most common means to exchange data with another computer on the internet is with the HTTPprotocol.
There are two fundamental parties to exchange data:
Client
- Initiates communication through a request.
server
- Receives &processes the request and sends a response in return.
IMan can act as both client via the Webservices functionality and server via the WebAPImodule.
In order to use either the Webservices capability or WebAPImodule you should have a good understanding of an Http Request and Response.
This page explains the basic fundamentals of the request and response with their common usages.
Http Request
A request is made up of several parts: the URL; the HTTPmethod; any headers; and the body.
The URL
Possibly the most important part of any request, this is the url or address of the resource.
A URLis made of multiple parts:
Scheme
- This is the first part of the url, either http or https (other schemes exist),
Server
- The server or host is the computer/service/server receiving the request.
Path
- Is a series segments where each segment is separated by a slash. The path points to the logical resource on the server.
Query
- An optional part at the end of the url preceded by a question mark (?). A query (as the name suggests) allows a queryable request to pass one or more parameters. Each parameter a key/value pair (key=value) where each parameter in a request is separated by either an ampersand or semi-colon.
Request Methods
HTTP defines methods (sometimes referred to as verbs) indicate the desired action to be performed on the identified resource.
IMan supports only GET, POST &PUTtype requests.
GET
- GETrequests query or ask the server for a resource. In a typical webservices scenario this is typically data, but the query could also be for an image, a file or html.
- GETrequests can optionally include a query to limit/restrict the range of data or resource to return.
- GETrequests typically do not include a body.
- Assuming a valid request the service should respond with desired resource. The response may be textual (data, html) or a binary format (pdf, image, other file type).
- This is the first part of the url, either http or https (other schemes exist),
POST
- POST requests are typically to send the service some data such as an order, an invoice, or customer.
- POST requests do not have a query string.
- POST requests typically have a body, which is the data (image, textual, file) being sent to the server.
- The response from a POST request will vary based on the request. The POST request may respond just with an acknowledgement of the request. Or posts to data services may respond with the full populated data record.
PUT
- PUT requests are similar to POST requests, they contain a body, typically have a response, but a PUTrequest typically indicates a resource on the server should either be updated or replaced.
- PUTrequests typically use a parameterised path to indicate the resource to update. In the example shown below the 1200 value within the path indicates the customer to be updated.
PATCH, DELETE, HEAD, MERGE (NOt Supported)
The HTTP protocol supports numerous other methods which perform different tasks at the service. Each method is implemented differently by the service you’re connecting with.
- PATCHrequests are similar to PUTbut differ that PATCHusually means to merge the request with existing resource vs. replace.
- DELETEindicates an existing resource should be removed/deleted.
Http Headers
HTTP headers let the client and the server pass additional information with an HTTP request or response. Headers typically are used to pass authentication values, indicate the content type of a request, the desired response content type, and other custom values.
An HTTP header consists of its case-insensitive name followed by a colon (:), then by its value. Whitespace before the value is ignored.
Example Headers
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; WOW64; Trident/5.0)
Authorization: Basic YjhiZWU5ZGNiYzgxODhjNlZjE4YjBkOWIwZjdjZTY=
Accept : application/json
Request Body
The body contains the data being sent to the data. The body may be textual or in a binary format.
As described, typically only PUTand POSTrequests contain a body, whereas GETrequests do not.
HTTP RESPONSE
The server, after processing the request will send a response.
A response contains a response code (to indicate the success or failure of a request), a set of headers and a body.
GET requests respond with the requested resource(s) whereas a POST request may respond with success indicator only, or it may respond with the fully populated resource which was inserted/posted.
Reponses may be textual or binary format.
Http Status Codes
Status codes indicate the success or failure of a request. They are a 3-digit number where the first digit signifies the class or category of response.
- 1xx informational response – the request was received, continuing processing.
- 2xx successful – the request was successfully received, understood, and accepted.
- 3xx redirection – further action needs to be taken in order to complete the request.
- 4xx client error – the request contains bad syntax or cannot be fulfilled.
- 5xx server error – the server failed to fulfil an apparently valid request.
Whilst this formal declaration exists, it’s ultimately up to each service to implement the specification. I.e. when should a 404 (not found) response be sent?
Http Headers
Response headers typically inform the client what type &encoding of the data is being returned and anything which may be pertinent e.g. any throttling data, whether data has been served from a cache, etc.
Response Body
The body contains the data returned from the server. The body may be textual or in a binary format.
