Web API Guide - How to Program

What HTTP methods (GET/POST) are supported by the Web API?

Parameters can be passed to the Web API using HTTP GET or POST methods. There is no change required in terms of which Parameters or their Values.
The two methods of submission are automatically recognized and handled by the Web API interface.

What is the format and URL address of a Web API GET call (hyperlink)?

A CGI script generates the HTML frames and pages that are displayed when someone clicks on a Web API URL. The general form of the Discovery Portal Web API GET call is defined below:

In the above HTML, Parameters et Values are place holders that you must replace with suitable text. The Values of these variables dictate the action that will be performed by the system and hence the resultant display. The question mark (?), equal signs ( >= ), and ampersands (&) are literal characters which you must include in the URL as indicated.

Users of the Web API should be aware that some browsers have limitations on the number if characters that can be passed using the GET method. This is why the POST method is also supported (as described below). Before a GET method URL is embedded in an HTML page, the Web API user should invoke the URL from a number of browsers, to ensure that no browsers have a problem with the length of the URL.

What is the format of a Web API post call?

The general format of the Discovery Portal Web API POST call is defined below:

Similar to GET calls, Parameters et Values are place holders that you must replace with suitable text. The Values of these variables dictate the action that will be performed by the system and hence the resultant display.

What Parameters and Values will the Web API CGI script accept?

Here are the different Parameters that you can specify, along with the possible Values for each. In most cases a Values is a literal string that must be specified exactly as shown below. However, any Values in the table which is enclosed in angle brackets (<...>) is variable, i.e. it is up to you to replace it with text appropriate for what you are trying to accomplish. The definitions of each of the actions that these Parameters invoke are provided in the following sections.

The order of the Parameters in the URL is not significant.

Always remember to insert an ampersand (&) between each Parameters =>Values pair that you specify in an URL. Note that some of the parameter Values have default >Values if they are not explicitly specified and if the base URL is specified with NO Parameters at all, then extensive on-line help information is returned to the requested browser.

the Request Parameters dictates the action that is to be performed and which other Parameters should be present on the URL, and their meaning. The Parameter Specifications section of the Web API Guide describes in detail each of the actions that are invoked by the use of each Request Value. 

Note that a " Product Collection" is another term for a database.

Is it necessary to specify one of every type of Parameter?

No, it is not necessary. Parameters fall into three categories:

• Required: the Parameters must always be specified in the URL.
• Optional: the Parameter may be omitted from the URL. Some optional Parameters have default Values that apply if a Parameters is not specified. This is defined in detail in the sections below.
• Conditional: the Parameter may or may not be required, depending on what Value you specify for the Parameter named Request.

As you can see, the table above showing every Parameter and possible Value also shows whether a Parameter is obligatory.

In most cases you are permitted to specify a given Parameter only once. The exception to this rule is the is obligatory named Target, which may be specified repeatedly, but only under certain circumstances. Details are given in the Parameter Specifications section of the Web API Guide.

How are errors in Parameters or Values indicated?

If you specify a combination of Parameters or Values that are illegal, incomplete, inconsistent, etc., then an HTML page will be returned. The HTML page will echo the path to the Web API and list the Parameter / Value pairs that were submitted. In addition, the HTML page will also contain a summary of the correct interface specification. This can then be used to diagnose the problem encountered or refresh your memory of the interface specification. 

What characters are permissible in a Web API URL?

Within any URL whose Parameters are passed using the HTTP get method, certain characters are determined to be unsafe or reserved, and thus need to be encoded by escape sequences. These escape sequences are of the format %<ASCII-character-hexadecimalvalue> . Unsafe characters are those that maybe interpreted by a browser or web server differently than intended. Reserved characters are characters which have special meaning within URLs, and must be coded so that they are not interpreted as their special meanings. These characters along with their escape sequences are listed below: 

Therefore, if you wanted to specify the database named:

as a Value ,you would have to convert its name to:

(note, that there is a hyphen in this example; it is one of the few non-alphabetic characters which can be used without requiring hexadecimal encoding). HTTP POST requests do not need this hexadecimal encoding. Value

For more information...

Should you have further questions please contact us via E-mail at:

[email protected]