LID URL Parameters

From LID Wiki

Many LID HTTP operations (regardless of LID 2.0 Profiles) carry parameters. Because standard web browsers are intended to be full-fledged LID clients, these parameters must be conveyed through standard HTTP facilities. This section describes how parameters must be used in a LID context.

Contents 1 Parameter Naming 2 Parameter Values 3 URL arguments or POST parameters? 4 URL arguments 5 Parameters for HTTP POST requests 6 Examples 6.1 As an HTTP GET request 6.2 As an HTTP POST request, parameters in payload 6.3 As an HTTP POST request, parameters mixed in URL and payload

Parameter Naming

All standard LID 2.0 parameters start with the magic prefix lid- (such as lid-action or lid-format), except for:

• the parameter called lid (conveying the client's LID URL), and
• the parameter called meta (obtaining meta-information)
• the parameter called xpath (conveying an XPath query).
• parameters defined in the OpenID specification, which start with openid..

Non-standard parameters must not start with the prefix lid.

Parameter Values

LID parameter values are most often text strings. However, in principle, they could also contain non-text, binary values. (see encoding below)

URL arguments or POST parameters?

LID HTTP operations can be performed equally using any HTTP verb, such as GET, POST, DELETE, PUT etc. that is appropriate for the respective operation; however, we encourage implementors to follow the principles outlined in the HTTP specification for when to use one HTTP verb over another to the maximum extent possible.

Note that parameter sequencing may be important. For example, the lid-credential parameter must be the last parameter specified when using credentials. All parameters provided as parameter in an HTTP POST request (and not in the URL itself) are considered to be following the arguments in the URL.

Also note that a parameter with the same name may be specified multiple times for the same request. Implementations are strongly encouraged to make sure they do not drop subsequent parameters with the same name.

URL arguments

LID parameters for HTTP operations on a URL U are being passed as arguments to U. If U already contains parameters, they are appended with a &; if it does not, they are appended with a ? for the first parameter, and & for the subsequent ones.

Both LID parameter names and parameter values are first properly escaped using the % syntax defined in the HTTP protocol standard.

Parameters for HTTP POST requests

LID parameters for LID HTTP POST requests to a URL U may be passed:

1. either as arguments to U, as in case of HTTP GET requests (see above)
2. or as the HTTP content/payload using the application/x-www-form-urlencoded MIME type (the same with which standard browsers submit HTML forms today). They are concatenated using &. However, the first character in the payload is always the first character of the first parameter name, never a & or a ?.

Both LID parameter names and parameter values are first properly escaped using the % syntax defined in the HTTP protocol standard.

Conceptually, the parameters passed as arguments to the URL, and the parameters passed as payload are considered concatenated in that sequence.

Examples

For example, the parameters lid-action=sso-approve and lid-target=http://firstsso.netmesh.org/ can be passed in the following ways to URL http://lid.netmesh.org/liddemouser:

As an HTTP GET request

This leads to an HTTP GET to the following URL:

http://lid.netmesh.org/liddemouser?lid-action=sso-approve&lid-target=http%3a%47%47firstsso.netmesh.org%47

As an HTTP POST request, parameters in payload

In this case, an HTTP POST is performed on URL http://lid.netmesh.org/liddemouser. The payload is of mime type application/x-www-form-urlencoded and contains:

lid-action=sso-approve&lid-target=http%3a%47%47firstsso.netmesh.org%47

As an HTTP POST request, parameters mixed in URL and payload

In this case, an HTTP POST is performed on URL http://lid.netmesh.org/liddemouser?lid-action=sso-approve. The payload is of mime type application/x-www-form-urlencoded and contains:

lid-target=http%3a%47%47firstsso.netmesh.org%47