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.
  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.
 

VWS Samples

Java and PHP code examples are available in the Downloads 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:

 
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.

 

 


Best Practices for Using the VWS API

The VWS Samples in Java and PHP demonstrate recommended practices for executing calls to Vuforia Web Services


Uploading new image targets

The VWS API allows users to upload new image targets programmatically into a Cloud Database and also to update existing image targets.

The upload and update operations are performed by HTTPS POST and PUT requests, as explained in How To Use the Vuforia Web Services API.

The execution of those requests on the Cloud Database can require additional time to be finalized. This means that a target for which an upload or update request has been issued needs time to propagate through the network before it can reach the active status and become usable for image recognition services. This action can take about 5 to 10 minutes.

Polling the target status

To establish whether a target has been successfully uploaded or updated on the Cloud Database, the client can periodically query and retrieve the current status of the target.

Because of the addition time needed, you should choose an appropriate time interval between GET queries. In particular, our recommendation is to perform such queries at intervals of 15 minutes or more.

VWS API calls – When you exceed the service quota

  • The VWS API for target management (to upload, update, and retrieve) can be used free of charge as part of the base-level service.
  • The base-level service is guaranteed to any developer as long as the number of API calls per day does not exceed a certain quota.
  • If you think you might exceed these levels, or if you receive an error message indicating that you have exceeded the allowed number of calls, please contact us.
  • You can tell us more about your app so that we can provide pricing and instructions to help select the appropriate service plan for your particular application.


Executing VWS API calls from a device

We strongly recommend against executing VWS API requests from your app as this can result in a service interruption if your API request quota is exceeded.  Instead you should relay requests from your app through a gateway server. This will enable you to manage your app’s request volume and prevent unexpected app behavior from causing a service interruption or shut down.