Interacting with the API resources
The API works over plain HTTP following REST conventions. You can list, get, create, update and delete resources using standard HTTP. The following table uses the customer resource as an example:
Action | HTTP method | Path |
---|---|---|
List customers | GET | /customers.xml |
Get customer with ID 1 | GET | /customer/1.xml |
Create a customer | POST | /customers.xml |
Update customer with ID 1 | PUT | /customers/1.xml |
Delete customer with ID 1 | DELETE | /customers/1.xml |
All programming environments have tools for making HTTP requests. In the examples below I'll use pseudocode and in addition show how to make the same request using the command-line tool cURL. We'll continue using the customer example.
To run these examples, you need to be authenticated and to provide a sender ID. You may also want to use the sandbox to play around without putting your real data at risk. I will be using the sandbox URL in the examples.
Content types
When interacting with the API you must tell it what format you want the returned data to be in, and if you're sending it data you need to tell it what format the data you're sending is in. Currently, we only support XML as the return format. When you send data to the API (i.e. data for creating a customer), it will most likely also be XML, but sometimes the API expects x-www-form-urlencoded (regular browser encoding). The format used will be stated in the documentation for each resource.
To tell the API what format you want the return data, add it as an extension to the URL. As we currently only support XML, every resource must be called with the .xml extension, e.g. /customers.xml
If you're sending data to the API, you must set the Content-Type HTTP header to either application/xml or application/x-www-form-urlencoded (most HTTP libraries will have funcionality to encode this for you by letting you set key-value parameters).
Encoding
All data to and from the Cargonizer API must use UTF-8. You should include the charset in your content type header: Content-Type: application/xml;charset=utf-8
If you're sending XML you should also specify that it's UTF-8 in the declaration: <?xml version="1.0" encoding="UTF-8" ?>
Examples
cURL micro tutorial
cURL is a widespread command-line tool for performing HTTP requests. Basic usage takes the form curl [arguments] [url] and here are some of the arguments you will run into throughout these documents:
- -X : Tells cURL which HTTP method to use (GET, POST, PUT, DELETE)
- -H : Adds a header to the HTTP request (for example, the X-Cargonizer-Key: 12345 header)
- -d : Sets the HTTP body. When given an at sign and a file name, it reads that file and uses it as the body Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.
cURL is very handy when getting to know a webservice; you see exactly what is going on between you and the server and you have complete control over what's getting sent.
Listing customers
cURLcurl -g -XGET -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers.xml'
HTTPGET /customers.xml HTTP/1.1 Host: sandbox.cargonizer.no X-Cargonizer-Key: 12345 X-Cargonizer-Sender: 678
Pseudocodehttp = new HTTPRequest(); http.method = 'GET'; http.url = 'https://sandbox.cargonizer.no/customers.xml'; http.headers.add('X-Cargonizer-Key', '12345'); http.headers.add('X-Cargonizer-Sender', '678'); response = http.execute();
Getting customer with ID 1
cURLcurl -g -XGET -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers/1.xml'
HTTPGET /customers/1.xml HTTP/1.1 Host: sandbox.cargonizer.no X-Cargonizer-Key: 12345 X-Cargonizer-Sender: 678
Pseudocodehttp = new HTTPRequest(); http.method = 'GET'; http.url = 'https://sandbox.cargonizer.no/customers/1.xml'; http.headers.add('X-Cargonizer-Key', '12345'); http.headers.add('X-Cargonizer-Sender', '678'); response = http.execute();
Adding a new customer
cURLcurl -g -XPOST Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den. -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers.xml'
HTTPPOST /customers.xml HTTP/1.1 Host: sandbox.cargonizer.no X-Cargonizer-Key: 12345 X-Cargonizer-Sender: 678 <contents of file "customer.xml">
Pseudocodehttp = new HTTPRequest(); http.method = 'POST'; http.url = 'https://sandbox.cargonizer.no/customers.xml'; http.headers.add('X-Cargonizer-Key', '12345'); http.headers.add('X-Cargonizer-Sender', '678'); http.body = new File('customer.xml').read(); response = http.execute();
Updating customer with ID 1
cURLcurl -g -XPUT Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den. -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers/1.xml'
HTTPPUT /customers/1.xml HTTP/1.1 Host: sandbox.cargonizer.no X-Cargonizer-Key: 12345 X-Cargonizer-Sender: 678 <contents of file "customer.xml">
Pseudocodehttp = new HTTPRequest(); http.method = 'PUT'; http.url = 'https://sandbox.cargonizer.no/customers/1.xml'; http.headers.add('X-Cargonizer-Key', '12345'); http.headers.add('X-Cargonizer-Sender', '678'); http.body = new File('customer.xml').read(); response = http.execute();
Deleting customer with ID 1
cURLcurl -g -XDELETE -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers/1.xml'
HTTPDELETE /customers/1.xml HTTP/1.1 Host: sandbox.cargonizer.no X-Cargonizer-Key: 12345 X-Cargonizer-Sender: 678
Pseudocodehttp = new HTTPRequest(); http.method = 'DELETE'; http.url = 'https://sandbox.cargonizer.no/customers/1.xml'; http.headers.add('X-Cargonizer-Key', '12345'); http.headers.add('X-Cargonizer-Sender', '678'); response = http.execute();