Definition of an URL for a REST API

When an URL is described it never includes the protocol ("https"), the host name ("example.org") a portnumber ("443") or the document root. So if the following example URL is described in this documentation:

https://example.com/pdp/sessions/75f10c44-6e33-4637-8006-3e432b65b751

it is reduced to this:

/pdp/sessions/75f10c44-6e33-4637-8006-3e432b65b751

and has to be extended when actually using this to call the REST API.

When there are variables within the URL these are enclosed by "{" and "}". The placeholder inside these curly braces is used as name in the documentation and printed italic. So to describe that the ID of the session has to be specified in the URL this would be stated like this:

/pdp/sessions/{session}

where you would have to replace the "{session}" with an appropriate value for the session's ID session.

MUST vs. MAY

When calling the REST API there are some parameters defined as a MUST and some parameters defined as a MAY. All MUST-parameters. If a parameter is defined by the URL that is called and enclosed by curly braces it is always a MUST-parameter. If you ignore this you are calling a different URL that might exist but do something different.