Table of Contents

Making Requests

RESTish Design

The SnapBill API is designed using REST principles (some, but not all.) The API runs over HTTP, and is located at https://api.snapbill.com/v1

You can access the entire API using only GET and POST requests. The reason for this is to maintain browsability but it also serves to simplify certain actions and the design.

GET (Discoverability)

GET requests form the discoverable layer of the API. They can be used to retrieve indexes and example forms with controls. 

    $ curl -u user:pass \
    >      https://api.snapbill.com/v1/client.json

File: examples/requests.txt-1.json - 

    {
      "code": 200,
      "type": "index",
      "index": {
        "add": "/v1/client/add",
        "list": "/v1/client/list",
        "{id}": "/v1/client/{id}"
      }
    }
    $ curl -u user:pass \
    >      https://api.snapbill.com/v1/client/add.json

File: examples/requests.txt-2.json - 

    {
      "code": 200,
      "type": "form",
      "controls": [
        {
          "type": "textbox",
          "name": "number",
          "caption": "Client Number"
        },
        {
          "type": "textbox",
          "name": "firstname",
          "caption": "First Name",
          "tip": "Used in friendly email templates - \"Hi John,\""
        },
        {
          "type": "textbox",
          "name": "surname",
          "caption": "Surname"
        },
        {
          "type": "email",
          "name": "email",
          "caption": "Email Address",
          "tip": "Required in order to email invoices"
        },
        {
          "type": "tel",
          "name": "cell",
          "caption": "Cellphone Number",
          "tip": "Useful for getting hold of client in emergencies"
        },
        {
          "options": [
            {
              "caption": "South African Rand",
              "key": "ZAR"
            }
          ],
          "multiple": false,
          "case": true,
          "type": "select",
          "name": "currency_code",
          "caption": "Currency",
          "tip": "Invoices and payments will be recorded in this currency",
          "default": "ZAR",
          "required": true
        },
        {
          "options": [
            {
              "caption": "Netcash Collect",
              "key": "netcash"
            },
            {
              "caption": "Other",
              "key": "other"
            }
          ],
          "multiple": false,
          "case": true,
          "type": "select",
          "name": "payment_method_code",
          "caption": "Payment method",
          "tip": "Setup more payment options in the Setup section",
          "required": true
        },
        {
          "type": "textbox",
          "name": "company",
          "caption": "Company name",
          "tip": "Shown as primary account name"
        },
        {
          "type": "textbox",
          "name": "discount",
          "caption": "Discount",
          "tip": "Discount given to user (%)"
        },
        {
          "type": "hidden",
          "name": "country_code",
          "value": "ZA"
        },
        {
          "type": "hidden",
          "name": "state",
          "value": "new"
        },
        {
          "type": "hidden",
          "name": "coupon",
          "value": ""
        },
        {
          "type": "textbox",
          "name": "data-vat_number",
          "caption": "VAT Number"
        },
        {
          "type": "textbox",
          "name": "data-public_street",
          "caption": "Street Address"
        },
        {
          "type": "textbox",
          "name": "data-public_postal",
          "caption": "Postal Address"
        },
        {
          "type": "textbox",
          "name": "data-public_city",
          "caption": "City"
        },
        {
          "type": "textbox",
          "name": "data-public_province",
          "caption": "Province / State"
        },
        {
          "type": "textbox",
          "name": "data-public_country",
          "caption": "Country"
        },
        {
          "type": "textbox",
          "name": "data-public_postcode",
          "caption": "Postal Code"
        },
        {
          "type": "textbox",
          "name": "data-public_phone",
          "caption": "Phone number"
        },
        {
          "type": "textbox",
          "name": "data-public_fax",
          "caption": "Fax number"
        }
      ]
    }

POST (Actions)

All standard requests to the API will be POST requests. These are used to add new clients (POST /v1/client/add), to list existing invoices (POST /v1/invoice/list) and to update (POST /v1/service/{id}/update) or delete (POST /v1/charge/{id}/delete).

Examples

PHP

In the example, we set the URL we'd like to call and initialise the curl object to point to that. Then we create an array of post data, and configure curl to use POST to make the request and to use our data array. 

<?php
 
$service_url = 'http://api.snapbill.com/v1/example';
$curl = curl_init($service_url);
$curl_post_data = array(
     "client_xid" => 'T:SA',
     "email" => 'email@example.com',
     );
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $curl_post_data);
$curl_response = curl_exec($curl);
curl_close($curl);
 
$xml = new SimpleXMLElement($curl_response);

We execute the request and capture the response. Health warning: by default curl will echo the response, if you want to parse it then you will need to use the CURLOPT_RETURNTRANSFER flag to have curl return the response rather than a boolean indication of success.

As you can see we've parsed the resulting XML and the script can then continue with the data it acquired. Depending what you need to do next, you can manipulate the SimpleXMLElement object as you need to.

If you're working with PHP and services, then hopefully this will get you started, if you have any questions or comments, then please email us.