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:

ActionHTTP methodPath
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

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();

Getting customer with ID 1

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();

Adding a new customer

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();

Updating customer with ID 1

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();

Deleting customer with ID 1

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();

 

 

 

Developer: Cargonizer API Documentation © Logistra AS   Øran Vest, 6300 Åndalsnes   Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.logistra facebook icon logistra twitter icon

Vi bruker informasjonskapsler (cookies) for å forbedre bruksopplevelsen og for å kunne føre statistikk over våre besøkende.