Web API Documentation

Contents

[edit] Overview

This page documents the Veer public-facing Web API.

[edit] Conventions used in this document

This document present examples of calling Veer Web API methods. These examples can be used by opening an openssl session to the web server:

openssl s_client -connect api.veer.com:443

Cut and paste the example into the telnet session. Remember that the HTTP protocol requires a single blank line between the headers of the request and the body content. Even when there is no body content, this blank line is still required.

You must have a Veer Web API Consumer Key and Secret pair to use the Web API. You may apply for such a key by contacting Veer.

[edit] Important notes

[edit] OAuth

We use an external library called OAuth.Net within our Web API and our sample .NET proxies. (You may obtain a copy of the sample .NET Proxy when you apply for and receive a Veer Web API Consumer Key and Secret.)

If you choose not to use our sample .NET proxies, or you are connecting to our Web API from another language, you must ensure that your requests conform to the HTTP protocol examples shown for the method you are calling. You must also ensure that your OAuth Authorization signature follows the specification.

For OAuth signed requests, we currently DO NOT sign the request body. The current OAuth specification is intended to sign x-www-url-formencoded content bodies, and our content bodies are either JSON or XML.

NOTE: We have not implemented the full OAuth authorization cycle. The Web API is currently tailored to installed applications, so we've chopped off much of the OAuth process and gone with a simple exchange of username/password credentials in exchange for an OAuth Access Token. We will eventually release the Web API for Web-based applications to use and at that time the entire OAuth authorization cycle will be implemented.

[edit] The api.veer.com site

The examples below use the site api.veer.com. Until we release the actual Web API at that location, please substitute api.sqa.veer.com anywhere you see api.veer.com. You may also subsitute api.dev.veer.com to hit the most recent development version of the API and api.local.veer.com to hit your local API, if you've chosen to install the Web API project on your local computer.

[edit] HTTP versus HTTPS

The Web API is available only through HTTPS. The example proxies connect as HTTPS to api.veer.com.

[edit] Web API versioning

The Veer Web API exists at api.veer.com. The Web API is versioned. Most Web API calls exist at /v1, with the exception of the Version service and the OAuth service, that are not versioned. Our intent is not to cause breaking changes to a published Web API method. When breaking changes are required, we will issue the method with a new version. For example, we may have two Web API calls such as:

https://api.veer.com/product/v1/methodA
https://api.veer.com/product/v1/methodB

If we need to make a breaking change to methodB, we'll create a new Web API as:

https://api.veer.com/product/v2/methodB

In this example, methodB will have two versions, an older one at /v1 and a newer one at /v2. There will only be one version of methodA. That means that the Web API at /v2 is sparse in comparison to the API at /v1. We won't automatically roll methodA into /v2 just because some other method required a new version.

Any new method will be issued under the /v1 version first. So we may introduce methodC. In that case, the complete API would look like:

https://api.veer.com/product/v1/methodA
https://api.veer.com/product/v1/methodB
https://api.veer.com/product/v2/methodB
https://api.veer.com/product/v1/methodC

[edit] Web API method deprecation

To be documented.

[edit] Web API URL structure

The Veer Web API attempts to follow a consistent naming convention. All URLs follow this format:

http://api.veer.com/service/v#/section/method/remaining

The first part after the site is the name of the service that hosts the method. The service is used to group like methods. Some services are Unprotected Web API calls, others are Protected Web API calls. The service is one of: version, oauth, commerce, customer, flont, product, or search.

Following the service will be the version, for those APIs that are versioned. It is typically /v1, but upgraded methods will appear with a higher version number. The version service and oauth service do not have a version number part in the url.

Following the service is the section within the service that hosts the method. This is yet another grouping of similar methods. Section names are dependent on the service. As an example, /information will contain methods that return information about some entity. Several services group methods under the /information section.

After the section is the name of the method is the thing being called.

The remaining parts of the URL contain information that is being provided to the method. The Veer Web API typically tries to include as much information as possible on the URL. In some cases though, information is transmitted in the HTTP request body via a POST or PUT operation.

[edit] Types of Web API methods

The public Web API is split into three categories: unprotected, protected and oauth. Within the Veer Web API, all the methods within a service are of the same type, they are either all Unprotected methods, or they are all Protected methods.

[edit] Unprotected API method calls

These API calls can be called without a customer being logged into the site. They typically involve things like searching and finding out information about products. Unprotected API calls require the Consumer Key to be present in either the User-Agent header or the custom X-Veer-Web-Api-Consumer-Key header of all requests. We use this for usage tracking. The following two unprotected API calls are equivalent:

GET /version/latest HTTP/1.1
Host: api.veer.com
User-Agent: valid-application-key
and
GET /version/latest HTTP/1.1
Host: api.veer.com
X-Veer-Web-Api-Consumer-Key: valid-application-key

We offer the custom header for those languages or systems that do not allow you to override the HTTP defined User-Agent header.

[edit] Protected API method calls

These API calls can be called after a customer has signed into the site. These calls typically deal with a customer in some way, such as retrieving their information and purchasing products. Protected API calls require the Consumer Key to be present in the OAuth Authorization field of all requests. An example Protected API call might look like:

GET /commerce/v1/information/credits HTTP/1.1
Host: api.veer.com
Authorization: OAuth oauth_consumer_key="valid-application-key" <remaining oauth parameters>

[edit] OAuth API method calls

For web applications, these API calls are used to obtain a Request Token, authorize the Request Token, and then exchange an authorized Request Token for an authorized Access Token.

For Installed applications, there is an API call that can exchange client credentials for an authorized Access Token.

[edit] On-the-wire data format

The Veer Web API can accept and return either JSON or XML. The type of data can be indicated by either the Accept header or the Content-Type header. The Web API always checks both headers. If the values of the two headers conflict, the Web API will use the value in the Accept header before the value in the Content-Type header. In the absence of either header, the Web API will choose JSON for both input and output. Acceptable values are for either header are:

  • application/json
  • application/xml
  • text/xml

[edit] JSON Accept header example

Here is an example Web API indicating it's intent to use JSON by setting the Accepts header:

GET /version/latest HTTP/1.1
Host: api.veer.com
User-Agent: valid-application-key
Accept: application/json

The response to that call will look like the following (note that line breaks have been added for clarity):

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.0
X-Marketplace-Return-Type: api.veer.com.VersionService+VersionInfo
Date: Wed, 09 Dec 2009 21:43:36 GMT
Content-Length: 193

{"majorVersion":1,"minorVersion":0,
 "downloadUri":"http:\/\/marketplace.veer.com\/web\/downloads\/valid-application.exe",
 "landingPageUri":"http:\/\/marketplace.veer.com\/web\/valid-application"}

[edit] XML Accept header example

Here is an example Web API indicating it's intent to use XML by setting the Accepts header:

GET /version/latest HTTP/1.1
Host: api.veer.com
User-Agent: valid-application-key
Accept: application/xml

The response to that call will look similar to the following (note that line breaks have been added for clarity):

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/7.0
X-Marketplace-Return-Type: api.veer.com.VersionService+VersionInfo
Date: Wed, 09 Dec 2009 21:46:16 GMT
Content-Length: 369

<VersionService.VersionInfo 
 xmlns="http://api.veer.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <majorVersion>1</majorVersion>
  <minorVersion>0</minorVersion>
  <downloadUri>http://marketplace.veer.com/web/downloads/valid-application.exe</downloadUri>
  <landingPageUri>http://marketplace.veer.com/web/valid-application</landingPageUri>
</VersionService.VersionInfo>

[edit] x-www-url-formencoded Content-Type header example

To comply with the OAuth specification, the Veer Web API only supports this content type in the Content-Type header of an OAuth service response. No other Web API call accepts or returns this format. An example OAuth service response will look similar to:

HTTP/1.1 OK
X-Marketplace-Return-Type: api.veer.com.Stream
Content-Length: 104
Content-Type: application/x-www-form-urlencoded

oauth_token=00000000-0000-0000-0000-000000000000&oauth_token_secret=00000000-0000-0000-0000-000000000000

[edit] HTTP methods

The Veer Web API uses standard HTTP methods when invoking a Web API method.

[edit] GET

All Web API calls that retrieve data will use a GET request. Such calls are idempotent. There is no body in a GET request. All the information to serve the request is either on the URL or is contained within the OAuth Authorization header. GET requests may be either Unprotected API methods or Protected API methods depending on the service being called.

[edit] POST

All Web API calls that cause data to change on the server will use a POST request. There may or may not be a body in a POST request. The Veer Web API tries to contain as much data as required to serve the request in the URL itself. POST requests are always Protected API methods and require an OAuth Authorization header.

[edit] PUT

All Web API calls that cause new data to be created on the server will use a PUT request. There may or may not be a body in a PUT request. The Veer Web API tries to contain as much data as required to serve the request in the URL itself. PUT requests are always Protected API methods and require an OAuth Authorization header.

[edit] DELETE

There are no Veer Web API calls that use a DELETE request.

[edit] HEAD

There are no Veer Web API calls that respond to a HEAD request.

[edit] OPTIONS

There are no Veer Web API calls that respond to a OPTIONS request.

[edit] HTTP X-Marketplace-Return-Type response header

The Veer Web API adds one additional custom header to all responses: X-Marketplace-Return-Type. Here is an example response:

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
X-Marketplace-Return-Type: api.veer.com.VersionService+VersionInfo

The content of this header is intended to be used by proxy writers to help decode the body content of a response. In the example above, the body contains a api.veer.com.VersionService+VersionInfo object. Our own .NET proxies make use of this header. It's use is optional depending on how you write your proxy.

All responses that succeed will return a 200-series status code. Typically the status code is 200 OK, but some methods may return another status within the 200-series.

[edit] HTTP error responses

The Veer Web API returns all error messages as strings contained within an error object. A sample error response might look like:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
X-Marketplace-Return-Type: api.veer.com.WebApiFault
Content-Length: 58

{"error":"ConsumerValidationStatus.ConsumerRejectedError"}

In this example, notice that the HTTP status is 403. All error responses return a standard HTTP status that makes sense for the situation. Note that the X-Marketplace-Return-Type header is set to api.veer.com.WebApiFault to indicate that the response body contains an error object.

The primary error message appears as a string of two parts separated with a period. The part to the left of the dot indicates the service from which the error originated. The part to the right of the dot indicates the problem encountered. In this example, the part to the left of the dot comes from the Web API consumer validation framework that runs before the actual code of the Web API method being invoked.

An error message may also contain a fields property if the request has multiple pieces that are each validated. When validation fails, the error property indicates the primary error, and each field that failed to validate will be listed in the fields property.

[edit] Dictionary

Consumer Key
The unique key that identifies a consumer of the application. When a developer applies to use the Web API, the Veer Web API Team will generate a unique Consumer Key for the developer's application. Each application must have it's own Consumer Key. The Consumer Key must be provided in the User-Agent header of all anonymous API requests, and must be present in the OAuth Authorization header for all protected API requests.
Consumer Secret
This is the shared secret between a developer's application and the Web API. When a developer applies to use the Web API, the Veer web API Team will generate a unique Consumer Secret for the developer's application. The Consumer Key and Consumer Secret are used to generate the OAuth Signature for protected API requests.
Idempotent
An element of data that is unchanged in value when operated on by itself. For example, a GET request will never cause data to change on the server.
Installed Application
An application that has been installed on a user's computer. Such applications are generally trusted by the user to obtain and use their username and password to access Veer.
OAuth Access Token
See Oauth.net.
OAuth Request Token
See Oauth.net.
Proxy
A body of code that translates the on-the-wire data into high-level objects and exceptions to another language.
Web API
A set of methods that can be used to interact with Veer using the standard HTTPS protocol.
Web Application
An application that runs within a web browser or handheld device. Such applications are generally untrusted by users.

Partner API method documentation

Documentation for the methods for our business-to-business Partner API can be found here. Everything up to this point, was the necessary background for being able to use the Partner API.

Web API method documentation

NOTE: In all the JSON and XML examples that appear in the Read more pages for each method, please be aware that the incoming and outgoing data has been word wrapped for clarity. That means that the Content-Length header does not match the request or response body as shown.

Application service

The Application service provides methods that can be used by a Consumer application in an anonymous manner, that is, without requiring an OAuth sign-in first.

https://api.veer.com/application/version

Returns information about the latest version of the application identified by the Consumer Key in the User-Agent header. Read more.

https://api.veer.com/application/customer/EMAIL/password

Sends a password reminder to the EMAIL specified. Read more.

https://api.veer.com/application/customer/register

Registers a new customer and sends the new customer a Welcome e-mail. Read more.

https://api.veer.com/application/information/countries

Gets a list of countries and regions that veer.com accepts. Read more.

https://api.veer.com/application/information/creditpacks/CURRENCY

Gets a list of credit packs that can be purchased using the specified CURRENCY. Read more.

Commerce service

The Commerce service offers methods for finding out commerce information about a customer as well as making purchases on behalf of a customer.

https://api.veer.com/commerce/v1/purchase/product/SKU/version/VERSION-ID

Purchases a version of a product on behalf of the customer. Read more.

https://api.veer.com/commerce/v1/information/purchased/product/SKU/versions

Obtains a list of the versions of a product that the customer has purchased. Read more.

https://api.veer.com/commerce/v1/purchase/credits

Purchases a credit pack on behalf of a customer and charges their credit card. Read more.

https://api.veer.com/commerce/v1/information/credits

Obtains information about how many credits a customer has currently. Read more.

Customer service

The Customer service offers methods for finding out information about a customer.

https://api.veer.com/customer/v1/information/short

Obtains short information about this individual that includes name but not addresses. Read more.

https://api.veer.com/customer/v1/information/address

Obtains the address for a customer if we have one on file. Read more.

https://api.veer.com/customer/v1/signout

Revokes further use of the Access Token for the individual it represents. Read more.

Oauth service

The OAuth service currently provides a single method that can be used by an Installed Application to exchange username and password client credentials for an authorized Access Token.

https://api.veer.com/oauth/installed/signin

Exchanges username and password client credentials for an authorized Access Token for the Consumer Key in the User-Agent header. Read more.

Product service

The Product service offers methods for finding out information about a product.

https://api.veer.com/product/v1/information/product/SKU/preview

Obtains preview information about the product specified by SKU. Read more.

https://api.veer.com/product/v1/information/product/SKU/versions

Obtains information about the versions of a product identified by SKU that are for sale. Read more.

Search service

The Search service provides methods to search the Veer catalog.

https://api.veer.com/search/v1/PRODUCT-TYPE/keywords/WORDS

Returns search results for the given product type that match the keywords. Read more.

https://api.veer.com/search/v1/PRODUCT-TYPE/artist/ID

Obtains a search result for a particular artist within a specific product type. Read more.

https://api.veer.com/search/v1/PRODUCT-TYPE/artist/ID/keywords/WORDS

Obtains a search result of all images with keywords for a particular artist within a specific product type. Read more.

Flont service

The Flont service provides methods to request URI's for font skus that can then be submitted to the Veer Flont engine. This is a translation layer that ensures your application can always request flont samples, regardless of the changes we make to the Flont engine URI structure itself.

https://api.veer.com/flont/v1/translate/sku

Obtains a URI that can be used to send a request to the Flont servers in exchange for a sample image of the font. Read more.

https://api.veer.com/flont/v1/translate/skus

Obtains multiple URIs that can be used to send requests to the Flont servers in exchange for a sample images of many fonts. Read more.