Developer Guide

URIs and resources

Two important concepts in REST APIs are resources and URIs.

A resource is anything that is important enough that connecting clients need to reference it directly. It could be an application, a license, a computer, etc. Resources can have other resources embedded, and such resources are called collection resources.

A URI (Uniform Resource Identifier) is used for referencing a resource. Every resource has an address that is unique for that particular resource. Think of an HTML document as an internet server. The document is the resource, and the URI is the unique address for that particular document. No other document has the same URI. The same is true in the API: No two applications share the same URI.

Resource representations

A resource is an entity living at a URI. It has a state that can be read and updated.

There is an important distinction between a resource and its representation. When you get a resource from the API, you're not getting the resource itself, but a representation of the resource's current state.

The REST API supports three different media types for representations: HTML, XML, and JSON. If a specific data format is preferred, specify the format using an Accept header when making the request:

Accept: text/html

- or -

Accept: application/xml

- or -

Accept: application/json

This is normally the recommended way to specify the media type. However, when browsing the API using an internet browser, you probably will not have any control over the Accept header. In this case, specify the preferred format using the $format query string parameter.

XML

https://MySLM/api/systemusers/loggedin?$format=xml

FormatXML.png

JSON

https://MySLM/api/systemusers/loggedin?$format=json

FormatJSON.png

Programmatic access

When accessing the Snow License Manager Web API programmatically, and depending on the language and programming environment, the authorization header might have to be constructed.

Perform the following steps:

  1. Combine the username and password into a string using the format: username:password

  2. Encode the resulting string using Base64

  3. Prepend the encoded string with "Authorization: Basic " (without the quotes)

Example 113.
  • username = jdoe

  • password = secret

Authorization: Basic amRvZTpzZWNyZXQ=

The example header was generated using the following C# program:

string username = "jdoe";
string password = "secret";
byte[] bytes = Encoding.ASCII.GetBytes(username + ":" + password);
string base64 = Convert.ToBase64String(bytes);
string header = "Authorization: Basic " + base64;


Collections and queries

All collection resources exposed by the API provide partial support for OData queries.

The API supports the following options:

  • $orderby

  • $top

  • $skip

  • $filter

  • $inlinecount

  • $format

Filter and order a collection using query string parameters on the URI of the collection resource. For more information on queries, see the OData query specification:

http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#QueryStringOptions