Things Every Developer Should Know

From Oxygen.next Wiki

1) You cannot make unlimited request and posts. API usage is rate limited. We have a primer that you should read to learn more.

2) The API is entirely HTTP-based Methods to retrieve data from the Oxygen API require a GET request. Methods that submit, change, or destroy data require a POST. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method. HTTP Response Codes are meaningful. This is what people call a RESTful API.

3) The API is a RESTful resource The Oxygen API attempts to conform to the design principles of Representational State Transfer (REST). Simply change the format extension ( *.xml or *.json ) a request to get results in the format of your choice. The documentation notes which formats are available for each method. The API presently supports the following data formats: XML and JSON formats.

4) Id's are unique HTTP Urls that link to the object. That makes it easy to use them :)

5) Parameters have certain expectations Some API methods take optional or requisite parameters. Two things to keep in mind when making requests with parameters: Parameter values should be converted to UTF-8 and URL encoded.

6) There are pagination limits Rest API Limit Clients may request up to 1,000 transactions via the page and count parameters for REST API methods. Requests for more than the limit will result in a reply with a status code of 200 and an empty result in the format requested.

7) Encoding affects status character count The Oxygen API supports UTF-8 encoding. Please note that angle brackets ("<" and ">") are entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers of JSON API output. When requesting XML, the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range may be translated to HTML entities.

8) You get get the current API Version by looking at the Header. The "X-Oxygen-API-Version" parameter is what you are looking for. You should make use of it to ensure compability with you client.

9) A command line is all you need to use the Oxygen API If your system has curl (and it should!), you’ve already got a great way to poke around the Oxygen API. Here are some examples:

Get the Current user object in XML, authenticated: curl -u username:password https://oxygennext.apigee.com/User

Get the Current team object in XML, authenticated: curl -u username:password https://oxygennext.apigee.com/Team

Learn more about cURL and the API here.

For get reguests a standard Webbrowser will do fine also!

10) We use apigee as proxy to manage traffic and monitor the service and we recommend you to also make use of it. If you want to use any other proxy thats fine too, but make shure it supports the "X-Forwarded-Host" Http Header. Be aware of that a proxy doubles the response time of every request!

11) Last but not least: If you need help, check the forum or community support. There is always a bunch of skilled people out there which can help!