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:

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
curl -g -XGET -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers.xml'

HTTP
GET /customers.xml HTTP/1.1
Host: sandbox.cargonizer.no
X-Cargonizer-Key: 12345
X-Cargonizer-Sender: 678

Pseudocode
http = 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();

cURL
curl -g -XGET -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers/1.xml'

HTTP
GET /customers/1.xml HTTP/1.1
Host: sandbox.cargonizer.no
X-Cargonizer-Key: 12345
X-Cargonizer-Sender: 678

Pseudocode
http = 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();

cURL
curl -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'

HTTP
POST /customers.xml HTTP/1.1
Host: sandbox.cargonizer.no
X-Cargonizer-Key: 12345
X-Cargonizer-Sender: 678
<contents of file "customer.xml">

Pseudocode
http = 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();

cURL
curl -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'

HTTP
PUT /customers/1.xml HTTP/1.1
Host: sandbox.cargonizer.no
X-Cargonizer-Key: 12345
X-Cargonizer-Sender: 678
<contents of file "customer.xml">

Pseudocode
http = 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();

cURL
curl -g -XDELETE -H'X-Cargonizer-Key: 12345' -H'X-Cargonizer-Sender: 678' 'https://sandbox.cargonizer.no/customers/1.xml'

HTTP
DELETE /customers/1.xml HTTP/1.1
Host: sandbox.cargonizer.no
X-Cargonizer-Key: 12345
X-Cargonizer-Sender: 678

Pseudocode
http = 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();