CNET API: Developer's guide
Contents
Audience
This document is intended for developers who want to integrate the CNET API into their websites. It assumes you are familiar with the basic concepts of APIs, XML, HTTP request methods, and the REST style of software architecture.
For a brief overview of the CNET API, see the quick start guide.
For reference information, see the reference guide.
Background technologies
The CNET API is a REST-based service that supports XML and JSON response formats. REST uses simple HTTP GET URLs to request resources.
One of REST's primary principles is based on exposing data as a series of interconnected entry points. For example, assume that resource A has a preexisting relationship to resource B. By following a URL returned with resource A, a client of the API should be able to traverse to the API's entry point of resource B. (For more information on REST, see Additional Resources.)
REST entry points (or "Resources")The following are the defined entry points (or "resources" in REST terminology) to the CNET API:
- Category (/category)
- Child Categories (/childCategories)
- Tech Product by ID (/techProduct)
- Tech Product Search (/techProductSearch)
- Software Product by ID (/softwareProduct)
- Software Product Search (/softwareProductSearch)
A category is used to classify products. CNET arranges products in a hierarchical ontology. For example, consider the following category breadcrumb: "Mobile Connectivity and Entertainment>Portable Audio Devices>MP3 players." MP3 players is a child category of Portable Audio Devices.
A tech product is a product available through CNET Shopper or CNET Reviews.
A software product is a software title available through CNET Downloads. To distinguish between subsequent software releases, software products are assigned to product sets. At any given time, there is one live product per product set. The one live product is the most recent release or version of the software.
For required and optional request parameters, as well as example request URLs for these API resources, see the reference guide.
Requests
The API service is built upon the HTTP protocol and uses HTTP GET requests to serve CNET data.
The basic structure of the request URLThe general structure of a request URL is as follows:
(URL has been cut for display purposes)
[optionalParam1]=[value]&partKey=[yourDeveloperKey]
Where:
- http://api.cnet.com/restApi/v1.0 is the base URL.
- /[resourceName] is the REST resource path.
- [requiredParam1]=[value]&[optionalParam1]=[value] are the required and optional parameters for that resource.
- partKey is your unique developer key. Every request URL requires a partKey.
Response structure
The default response format is an XML document with a <CNETResponse> root element. A valid request will return a <CNETResponse> object with response data represented as child nodes. To receive a response in JSON format, add &viewType=json to the request URL. For more information, see the reference guide.
Sample XML success response
<CNETResponse version="1.0">
<TechProduct>...</TechProduct>
</CNETResponse>
An invalid request or an error condition will result in an <Error> element with a non-200 error code and possibly a child <ErrorMessage> element. The response error codes are based loosely on HTTP status codes.
<CNETResponse version="1.0">
<Error code="400">
<ErrorMessage>Error #1: Invalid request</ErrorMessage>
<Error>
</CNETResponse>
Best practices
The following best practices are intended to:
- Help ensure backward compatibility with future releases of the CNET API.
- Maximize performance and scalability of your application.
Client applications should parse the response XML in a way that will not break when the following events occur:
- New XML elements or attributes are added to the response.
- The order of XML elements or attributes change.
The iod parameter is used to specify what optional data should be included in a given response. (To see its possible values, see the reference guide.) When using iod, follow the salad bar rule of thumb: Take only what you can eat.
Explicitly list the data sets you desire so that the resulting response is not unnecessarily verbose (for example, iod=hlPrice,offers). This helps to improve the performance of your application.
Caching guidelinesCaching is recommended, but it must be performed in accordance with the following guidelines:
- Data displayed to end users (i.e. products, offers, and search results) must be shown in the order returned by the API.
- CNET data may only be stored in memory. It may not be stored on a disk, in a database, or on a file system. In-memory caching guidelines are summarized in the following table.
Data Type Recommended Maximum Cache Expiration Time Category Data 1 day 7 days Tech Product Data 1 hour 6 hours Software Product Data 1 hour 6 hours
Additional resources
