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

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.

Get started

Follow these steps to get started using the VWS APIs.

  1. Log in to the Target Manager using your Vuforia Engine 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 Database in the Target Manager.

Access keys

Each database has two keys – the server access key and the client access key.

  • The Server Access Keys are used for uploading and managing images via the VWS API. The server access keys have both read and write permissions on the database.
  • The Client Access Keys allow an app to query the database for image recognition services. The Client Access Keys have read-only access on the database. The Client Access Keys need to be embedded in the application and passed to the Vuforia Engine 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.

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.

All VWS API calls must include the Authorization header:

Authorization: VWS {server_access_key}:{Signature}

The server_secret_key is the public 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: This is the HTTP method used for the action, for example, GET, POST, and so forth.
  • Content-MD5: This 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: It is the content-type of the request body (like multipart/form-data). Use an empty string for request types without a request body.
  • Date: This 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.

  • Request-Path: This path needs to include the entire URL of the request, e.g. when updating a target the Request-Path would be "https://vws.vuforia.com/targets/{target_id}", where target_id is the specific ID of the target to be updated.

NOTE: A valid time-stamp (using the HTTP Date header) is mandatory for authenticated requests.

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.

Can this page be better?
Share your feedback on our community forum