RESTful interface principles in the web services

The web services are a RESTful interface. Key principles used by the web services include the following.

Providing access to individual resources

A key principle in the web services system is providing access to individual resources. Manageable items in this system, including data elements and control endpoints, have unique identifiers and are arranged in a hierarchy. Using this system, you can locate any item in the web services system by its URI.

Granularity based on independence of resources

For many items that can be requested and returned by the web services system, reading, and in some cases writing, an element as an individual entity is a natural operation. For other items, dividing groups of objects into individual fields may be unreasonable, because the web services system may be incapable of manipulating the objects independently. For such items, the “resource” at the web services level is a collection of the related values. Where possible, the web services system makes available individual data elements.

Leveraging HTTP operations

The HTTP specification allows for a variety of useful operations, including GET, PUT, POST, and DELETE. The RESTful interface maps logical operations to HTTP request types. For example:

Use GET to perform a “read” operation.
Use PUT to perform a “write” operation.
POST is reserved for control elements with an RPC-style interface, such as passing parameters and getting a response.
Use DELETE to remove elements capable of being deleted.

Leveraging HTTP security

The only security specified in web services is HTTP-related access control. The web services provide access to URLs with the same level of security as any web page in the system.

If HTTP is enabled:

There is no access-level security by default.
There is encryption, but no other security by default.

If basic authentication is enabled for the WVA, the web services user must enter the WVA username and password to access the web services system. The web services user may be an application or a user at a browser.

username: admin
default password: admin

For more information on the different types and levels of security implemented in the WVA, see Security features in the WVA.

Support for multiple content types

Web tools support a variety of methods for expressing data. The web services interface is sensitive to the content type-related HTTP headers in order to determine the format of a request and the format to use for a response. The same information is conveyed, and only the data format may change between the content types.

To request a specific format, an HTTP request includes an Accept header, with a MIME-type matching the desired format. All successful responses include a Content-Type header that indicates the MIME type of the response payload. Available content types are:

HyperText Markup Language (HTML): text/html
Extensible Markup Language (XML): application/xml
JavaScript Object Notation (JSON): application/json

See the Index of web services resources for indicators as to which types are applicable to which URIs.

WVA security and protected URIs

On the WVA, some URIs are password-protected. The Index of web services resources indicates password-protected URIs by an x in the Protected URI column. Protected URIs are intended to be used only by administrators to configure the device. Other URIs are available to an application for normal operations.

If basic authentication is enabled, PUT and DELETE operations applied to a protected URI require authentication. Unprotected URIs do not require authentication. A GET operation to any URI also does not require authentication.

On any non-WVA devices that implement web services, all methods on all URIs require authentication if enabled.

Generally, interface devices using web services, such as a smart phone or tablet, should not have access to the resources that require authentication.