Vuforia Web Services

The Vuforia Web Services ( VWS ) API is a RESTful web API that enables developers to use their own Content Management System (CMS) with Vuforia’s Cloud Recognition service and VuMark Generation API. Developers can implement the VWS API in their CMS to query Cloud Databases, upload Image Targets to a Cloud Recognition Database, add application metadata, and monitor the status of their databases and targets. They can also use VWS to retrieve printable instances of VuMarks.

Use Cases

The VWS API can be used for developing content management solutions that communicate with the Vuforia Cloud Recognition service.

Working with the VWS API

VWS is a RESTful API executed via HTTP. VWS API calls can be implemented in any language and context capable of making a valid HTTP request to a remote host. See: How To Use the Vuforia Web Services API

Get started

Follow these steps to get started using the VWS APIs.
  1. Log into the Target Manager using your Vuforia developer account and sign up for Cloud Recognition service.
  2. Create a cloud database using the Target Manager, See: How To Create a New Cloud Database.
  3. Download the server access keys from the Access Keys tab for your Cloud Databaes in the Target Manager.

Access keys

Each database has two keys – the server access key and the client access key.
  • The server access key is used by VWS to query, upload and manage images in the database. The server access key has both read and write permissions on the database.
  • The client access key allows an app to query the database for image recognition services. The client access key has read-only access on the database. The client access key is embedded in the application and passed to the Vuforia SDK during initialization of the Vuforia::TargetFinder.

All APIs are blocking calls – that is, they return only when all of the processing is finished, so it is important to design your app UI to expect some delay on the more complex calls.

Security

All API calls use HTTPS with TLS 1.0, or greater, with mutual server authentication. In addition, a special header field is calculated to ensure that only authorized access is allowed on each database.

Making API Calls

1. Add the server access key to the header of any VWS requests, see below.
2. Submit a well formed VWS API request to https://vws.vuforia.com via HTTP.
3. Parse the JSON body of the VWS API request response.

VWS API must include an authorization header field.

All calls to use the VWS API must include the authorization header field. The field looks like the following example:
Authorization: VWS {provision_access_key}:{Signature}

The server_secret_key is the public server key that is provided when you set up your Cloud Recognition Database.

The Signature is a string that is formatted from the concatenation of these fields..

Signature = Base64(HMAC-SHA1(server_secret_key, StringToSign ) ) ;
StringToSign =
  HTTP-Verb + "\n" +
  Content-MD5 + "\n" +
  Content-Type + "\n" +
  Date + "\n" +
  Request-Path;

Where:

  • HTTP-Verb is the HTTP method used for the action, for example, GET, POST, and so forth.
  • Content-MD5 is the hexadecimal MD5 hash of the whole request body (from the first boundary to the last one, including the boundary itself). For request types without request body, include the MD5 hash of an empty string which is “d41d8cd98f00b204e9800998ecf8427e”.
  • Content-Type is the content-type of the request body (like multipart/form-data). Use an empty string for request types without a request body.
  • Date is the current date per RFC 2616, section 3.3.1, rfc1123-date format, for example,
    Sun, 22 Apr 2012 08:49:37 GMT.
  • NOTE: The date and time always refer to GMT.
See:
How To Use the Vuforia Web Services API
How To Interpret VWS API Result Codes

VWS Samples

Java , PHP and Python code examples are available in the samples section of the developer portal.

Example - Java:

  1. The sample code is provided in a zip file. You must unzip the file in a working directory to review the code and update the security keys.
  2. The zip file contains the following six files:
    • DeleteTarget.java
    • GetAllTargets.java
    • GetTarget.java
    • PostNewTarget.java
    • SignatureBuilder.java
    • UpdateTarget.java
  3. After you have these six files in your working directory, you must update all the files by entering your access_key and secret_key values.

For example, the DeleteTarget.java file would look like the following code:

(JSON)
public class DeleteTarget {
 
   String access_key = "<your server access key here>";
   String secret_key = "<your server access key here>";
   String targetId = "<your targetID here>";
   String url = "https://vws.vuforia.com";
…
  1. Replace the placeholders between the quotes (“”) with their appropriate values for access_key, secret_key, and targetID.