Recommendation for client implementations

This page is targeted at developers of client implementations using the HTTP interface, not general users.

HTTP connections

The servers support HTTP/1.1 persistent connections. Clients which make multiple calls in quick succession, particularly when using SSL, should make use of this to reduce the load on the server.

HTTP/1.1 clients may receive chunked transfer encoded responses. If they are not prepared to deal with this then they should announce themselves as HTTP/1.0 only.

Informational headers

In order to assist with user support, clients should send a User-Agent header identifying the client and its version, and a From header identifying the user. The latter should have the format username@hostname (it is not necessary for this to be a valid email address). Where the client is being used in a Grid job, it is preferable to provide the actual username rather than the group account name.

Response content type

The samweb server uses the Accept header to determine the content-type of the response for API methods. The default in most cases is text/plain, and application/json and text/html are also supported by some methods. Methods which support this also support a format=<format> parameter, where <format> can be plain, json, or html in order to explicitly set the returned type. The Accept header also affects the type of returned error messages. The accept header is only a suggestion, and responses may be returned with a different content-type, so applications should verify the type before using it.

Encrypted connections

Encrypted connections require a client certificate. Any OSG approved CA is supported. Methods which modify the database generally require encryption. Since the primary purpose of the encrypted connection is for the server to authenticate the client, applications may wish to skip verifying the server certificate (note - the python urllib2 http client library does not support certificate verification). If the server certificate has not been verified, the client should not send any secret information (such as passwords) to the server. (Currently, no SAMWeb method requires transmitting passwords or confidential information).

Because of the overhead of encryption, clients calling frequently polled methods like getNextFile should not use encryption.