Subscribe to Blog via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Join 13 other subscribers

Getting Started with Netbreeze API

/Getting Started with Netbreeze API
Getting Started with Netbreeze API 2013-04-14T18:50:24+00:00

Getting Started with Netbreeze API

This guide covers everything you need to understand basic principles of the Netbreeze API. After reading it, you should be familiar with:

  • Authenticating your API requests
  • Retrieving a document feed
  • Handling error responses

This guide is based on API version 1 (v1).

REST API

The Netbreeze API provides an easy way to access and edit data via a RESTful web service. The basic API endpoint under which all methods are located is:

https://data.netbreeze.ch/api/version/v1/

Access Authentication

Access is restricted to authorized users and requires username and password with every request. The API relies on HTTP basic authentication which uses your Base64 encoded username and password:

base64_encode('username:password') => dXNlcm5hbWU6cGFzc3dvcmQ==

Use your own username and password instead to access the API.

Make sure to add your authentication token to the HTTP header of each of your requests:

GET / HTTP 1.0
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ==

Security

The API supports encrypted communication via HTTPS. It also allows unsecured access via HTTP but we strongly encourage our users to make use of secure transfer.

Reading data

In this example we use the Full Document Feed functionality to fetch a list of documents for the solution with the ID 3293. It retrieves at most 2 documents (content and meta data) for the solution starting with the document ID 40000359.

Request:

GET https://data.netbreeze.ch/api/version/v1/solutions/3293/fullfeed?fromId=40000358&size=2 HTTP 1.0
Accept: application/JSON
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ==
The Netbreeze API supports responses in JSON and XML. So, to request an XML response simply use 'Accept: application/XML'.
JSON-Response (with HTTP Status Code 200):
{
"Documents": {
"Document": [
{
"aquisitionDate": "2012-01-01-05:22:22",
"channel": "Blogs",
"contentText": "Press Release: HERNDON, Va., September 1, 2011 ? Audi has left nothing untouched in the newly redesigned Audi A6, from the exterior?s classic, yet contemporary appearance to a variety of powertrain options that include the award-winning 2.0 TFSI® and 3.0 TFSI engines. Impressive performance and efficiency contribute to the overall appeal of the all-new 2012 A6, as does the exterior. The extended wheelbase shortens overhangs to give the Audi A6 a more performance-oriented look while delivering improved ride quality and ...Source: http://www.distrocars.com/2012-audi-a6-3-0-tfsi-quattroRussell William Wallace Jr Blake Griffin DuPont National Guard Military Intelligence Johnny Andrew Sauter Detroit Pistons Bobby Labonte",
"id": "40000359",
"language": "en",
"publicationDate": "2011-12-31-23:43:09",
"publisher": "jesamputian - jesamputian.typepad.com",
"title": "2012 Audi A6 3.0 TFSI Quattro Lightweight Construction & MMI System with Supercharged V6 Engine 310 hp Torque 325 lb-ft 8 Speed Tiptronic Transmission",
"URI": "http://jesamputian.typepad.com/blog/2011/12/2012-audi-a6-30-tfsi-quattro-lightweight-construction-mmi-system-with-supercharged-v6-engine-310-hp-torque-325-lb-ft-8-spe.html",
"visibility": "0"
},
{
"aquisitionDate": "2012-01-01-05:22:25",
"channel": "Blogs",
"contentText": "AUDI WHEEL CENTER HUB CAP A4 A6 QUATTRO RS6 TT ALLROAD 18 " WHEELS by Audi Buy new: $35.95 (Visit the Hot New Releases in Wheels & Tires list for authoritative information on this product ' s current rank.)Find the best price Click Here",
"id": "40000362",
"language": "en",
"publicationDate": "2011-12-31-21:04:00",
"publisher": "raya - wheelss45.blogspot.com",
"title": "AUDI WHEEL CENTER HUB CAP A4 A6 QUATTRO RS6 TT ALLROAD 18" WHEELS",
"URI": "http://wheelss45.blogspot.com/2011/12/audi-wheel-center-hub-cap-a4-a6-quattro.html",
"visibility": "1"
}
]
},
"nextRequestURL": "https://data.netbreeze.ch/api/version/v1/solutions/3293/fullfeed?fromId=40000362&size=2",
"size": "2",
"totalHits": "45535"
}

Error Codes

If an error occurred, the Netbreeze API will tell you by returning a corresponding HTTP status code. Netbreeze API sends the following standard REST error codes:

Code Status Reason
400 Bad Request If a request contains invalid parameters.
401 Unauthorized If the authorization failed (wrong username/password).
404 Not Found If the requested URL is wrong. In this case the Netbreeze API might also send a short description in plain text.
500 Internal Server Error If the request could not be properly processed by the back-end.
503 Service Unavailable If the service is down due to technical difficulties or maintenance.

Access Restrictions

Unless noted otherwise, the number of requests per client is limited to 10 requests per minute.