Rest API for Vendors

Diglib provides vendors with a REST interface so that vendors can integrate their own systems with Diglib.

Endpoints

Diglib provides three service endpoints:

SiteAgreementService.svc

SiteAgreements service provides a consumer with the following operations matrix

HTTP Method
 Relative webservice URL
Description
GET  /SiteAgreements Gets all siteagreements from your publisher (See example 1)
GET  /SiteAgreements/{siteAgreementId} Gets single siteagreement based on {siteAgreementId} (See example 2)
PUT  /SiteAgreements/{siteAgreementId} Updates single siteagreement (See example 3)
POST  /SiteAgreements Creates a new SiteAgreement. Returns an XML description of the created siteagreement, including the {siteAgreementId} for future use (See example 4).
DELETE  /SiteAgreements/{siteAgreementId} Deletes specified siteagreement based on {siteAgreementId}
 

ResourceService.svc/Resources

HTTP
Method
 Relative webservice URL
Description
GET  /Resources Gets all resources from your publisher (See example 5)

CustomerService.svc/Customers

HTTP
Method
 Relative webservice URL
Description
GET  /Customers Gets all customers available (See example 6)

Security

Security for the Diglib REST API is handled with a signed Authorisation header in the request.

The header is on the form:

Authorization: {ApplicationKey}#{TimestampInMillis}#{Signature}

In Diglib’s admin interface, you can check what your ApplicationKey and SharedSecret are. The shared secret is used for HMACMD5 hashing when you generate the signature part.

Timestamp:  Milliseconds since 01.01.1970 in UTC time.

Code example how the timestamp may be constructed in C#

DateTime t = DateTime.UtcNow;
DateTime REFERENCE_TIME =  new  DateTime( 1970,01,01,00,00,00,01, cultureInfo.Calendar );


TimeSpan dt = t - REFERENCE_TIME;


long totalSeconds = (long)dt.TotalSeconds;

Code example how the timestamp may be constructed in Java

Calendar c = Calendar.getInstance();


long l = c.getTimeInMillis();

Signature: Generated by concatenating ApplicationKey + Timestamp, and doing an HMAC MD5 hash on the concatenated string with the shared secret as salt. The signature must be converted to a BASE64 encoded string when sending.

Code example of how to generate the signature:

The examples are based on that you have the shared secret as String secret, and String toBeHashed as the concatenation of ApplicationKey+Timestamp (without the # signs).

In Java:

SecretKeySpec  pkey = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacMD5");
// Get instance of Mac object implementing HMAC-MD5, and
// initialize it with the above secret key
Mac mac = Mac.getInstance("HmacMD5");
mac.init(pkey);
byte[] result = mac.doFinal(toBeHashed.getBytes("UTF-8"));
return new BASE64Encoder().encode(result);

And in C#:

byte[] saltValueBytes = Encoding.UTF8.GetBytes(secret);

HMACMD5 myHash = new HMACMD5(saltValueBytes);
myHash.ComputeHash(Encoding.UTF8.GetBytes(toBeHashed));
return Convert.ToBase64String(myHash.Hash);

Failure to include the authorization header in a REST request will result in a 403 forbidden HTTP response. This is done in order to secure your data in a simple manner.

Rest API Examples of request results and request bodies for the services

1. Get all site agreements result:

<ArrayOfSiteAgreement xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<SiteAgreement>

<ID>1</ID>

<CustomerID>201</CustomerID>

<CustomerName>My customer 1</CustomerName>

<ExternalId>SiteAgreementX</ExternalId>

<CreationDate>2009-05-12T10:24:56</CreationDate>

<ValidToDate>2009-07-01T00:00:00</ValidToDate>

<ValidFromDate>2009-05-12T00:00:00</ValidFromDate>

<IncludeAllResources>true</IncludeAllResources>

<Resources i:nil="true" />

</SiteAgreement>

<SiteAgreement>

<ID>4</ID>

<CustomerID>202</CustomerID>

<CustomerName>My customer 2</CustomerName>

<ExternalId>SiteAgreementY</ExternalId>

<CreationDate>2009-06-02T05:57:13</CreationDate>

<ValidToDate>2009-07-11T00:00:00</ValidToDate>

<ValidFromDate>2009-06-02T00:00:00</ValidFromDate>

<IncludeAllResources>false</IncludeAllResources>

<Resources>

<Resource>

<ResourceID>629</ResourceID>

<ExternalId>MyResourceX</ExternalId>

<Title>My resource 1</Title>

<Description>The best resource</Description>

</Resource>

<Resource>

<ResourceID>624</ResourceID>

<ExternalId>MyResourceY</ExternalId>

<Title>My resource 2</Title>

<Description />

</Resource>

<Resource>

<ResourceID>627</ResourceID>

<ExternalId>MyResourceZ</ExternalId>

<Title>My resource 3</Title>

<Description />

</Resource>

</Resources>

</SiteAgreement>

</ArrayOfSiteAgreement> 

2. Get single site agreement result:

<SiteAgreement xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<ID>4</ID>

<CustomerID>202</CustomerID>

<ExternalId>SiteAgreementY</ExternalId>

<CustomerName>My customer 2</CustomerName>

<CreationDate>2009-06-02T05:57:13</CreationDate>

<ValidToDate>2009-07-11T00:00:00</ValidToDate>

<ValidFromDate>2009-06-02T00:00:00</ValidFromDate>

<IncludeAllResources>false</IncludeAllResources>

<Resources>

<Resource>

<ResourceID>629</ResourceID>

<ExternalId>MyResourceX</ExternalId>

<Title>My resource 1</Title>

<Description>The best resource</Description>

</Resource>

<Resource>

<ResourceID>624</ResourceID>

<ExternalId>MyResourceY</ExternalId>

<Title>My resource 2</Title>

<Description />

</Resource>

<Resource>

<ResourceID>627</ResourceID>

<ExternalId>MyResourceZ</ExternalId>

<Title>My resource 3</Title>

<Description />

</Resource>

</Resources>

</SiteAgreement> 

3. Update single site agreement request body (Content-Type of the request should be text/xml):

<SiteAgreement xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<CustomerID>202</CustomerID>

<ExternalId>SiteAgreementY</ExternalId>

<ValidToDate>2009-07-11T00:00:00</ValidToDate>

<ValidFromDate>2009-06-02T00:00:00</ValidFromDate>

<IncludeAllResources>false</IncludeAllResources>

<Resources>

<Resource>

<ResourceID>629</ResourceID>

</Resource>

<Resource>

<ResourceID>624</ResourceID>

</Resource>

<Resource>

<ResourceID>627</ResourceID>

</Resource>

</Resources>

</SiteAgreement> 

4. Create a new site agreement request body (Content-Type of the request should be text/xml):

<SiteAgreement xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<CustomerID>202</CustomerID>

<ExternalId>SiteAgreementY</ExternalId>

<ValidToDate>2009-07-11T00:00:00</ValidToDate>

<ValidFromDate>2009-06-02T00:00:00</ValidFromDate>

<IncludeAllResources>false</IncludeAllResources>

<Resources>

<Resource>

<ResourceID>629</ResourceID>

</Resource>

<Resource>

<ResourceID>624</ResourceID>

</Resource>

<Resource>

<ResourceID>627</ResourceID>

</Resource>

</Resources>

</SiteAgreement> 

5. Get all resources:

<ArrayOfResource xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<Resource>

<ResourceID>629</ResourceID>

<ExternalId>MyResourceX</ExternalId>

<Title>My resource 1</Title>

<Description>The best resource</Description>

</Resource>

<Resource>

<ResourceID>624</ResourceID>

<ExternalId>MyResourceY</ExternalId>

<Title>My resource 2</Title>

<Description />

</Resource>

<Resource>

<ResourceID>627</ResourceID>

<ExternalId>MyResourceZ</ExternalId>

<Title>My resource 3</Title>

<Description />

</Resource>

</ArrayOfResource>

 

6. Get all customers:

<ArrayOfCustomer xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<Customer>

<CustomerID>1</CustomerID>

<Name>Customer 1</Name>

</Customer>

<Customer>

<CustomerID>2</CustomerID>

<Name>Customer 2</Name>

</Customer>

</ArrayOfCustomer>