Pulling Data
The Fizz API makes pulling data as simple as requesting a web page. In fact, you can use your browser to test things out.
Token based authentication
As discussed on the authentication page, a security token must be passed with every request. Let's pretend that your security token is "TOKEN" (instead of one of those delicious GUIDs), if you want customer 12, you can't request:
/fizz/customers/12.xmlYou need to add on the token. So the full URI would look something like this:
/fizz/customers/12.xml?token=TOKEN
Pages of data
For any request that will return multiple records, fizz requires at least two parameters: the token (of course), and the page number. Fizz will only return 10 records for each request. So if you request:
/fizz/customers.xml?token=TOKEN&page=1and get back 10 records, then you'll want to request:
/fizz/customers.xml?token=TOKEN&page=2After you request a page that returns less than 10 records, there is no need to go any further. Please note that since this page parameter must be sent for any GET request that returns multiple records. So, you'll also need it for nested records like this:
/fizz/customers/12/addresses.xml?token=TOKEN&page=1
Filtering data
To filter the data for things that have been updated recently, just include the "since" parameter. You can pass in a date, or a date and time. Just make sure the format conforms to ISO 8601:
/fizz/customers.xml?token=TOKEN&page=1&since=2009-04-01Alternately, you can filter the data by the fizzid also. Just remember to include the page param too.
/fizz/customers.xml?token=TOKEN&page=1&fizzid=1234And you filter by empty values by passing in an empty string for the value. This is very useful for finding records that don't have a fizzid yet.
/fizz/customers.xml?token=TOKEN&page=1&fizzid=You can also combine filters. Here is a request to get all customers with no fizzid that have been updated since april 1st.
/fizz/customers.xml?token=TOKEN&page=1&fizzid=&since=2009-04-01
Sorting data
To sort the data, include the "sort" parameter. The value of the sort param should be the name of the field that you want to sort by. So, let's get the customers sorted by zip code:
/fizz/customers.xml?token=TOKEN&page=1&sort=zip
If you want to sort in reverse order, just use a minus sign before the name of the field. Here is how you can get the syncs, most recent first:Warning: When retrieving multiple pages of data, you should only sort by fields that will not change (e.g. id, and created-at). If you sort by a field that can be modified, you could end up with a race condition. For example, let's say that you have 15 customers and you try to sort by first-name.
- You request /fizz/customers?sort=first-name&page=1
- A user changes a customer's first name from William to Bill
- You request /fizz/customers?sort=first-name&page=2
Since you were sorting by first-name, you will miss Bill completely, because he moved from page 2 to page 1 between your two requests. If you sort by a immutable field, like the id field, this won't be a problem.
If you are just trying to find a single record, and using the sort to bring that record to the front of the list, then you don't need to worry about this problem. For example, if you want to find the customer record that was updated most recently, you could GET /fizz/customers?page=1&sort=updated-at and grab the first record. As long as you don't request page 2, you will be safe.
/fizz/syncs.xml?token=TOKEN&page=1&sort=-created-at
If you don't set the sort parameter, Fizz will default to sorting by the created-at field.
Examples
Here are a few examples using everyone's favorite tool...curl. (We've omitted the full urls for the sake of brevity.)
#all customers (first page) curl -X GET /fizz/customers.xml?token=TOKEN&page=1 #customers updated after March 3 2010 curl -X GET /fizz/customers.xml?token=TOKEN&page=1&since=2010-03-03 #customer with an id of 12 curl -X GET /fizz/customers/12.xml?token=TOKEN #addresses for the customer with an id of 45 curl -X GET /fizz/customers/45/addresses.xml?token=TOKEN&page=1
Sample data
Here are some samples of the XML that you can expect from your Fizz requests. It's also the format that you should use when you are pushing data into Coolfront Mobile. (We've omitted the full URL and query parameters for brevity.)
request | returns |
---|---|
/fizz/customers.xml |
<?xml version="1.0" encoding="UTF-8"?> <customers> <customer> <account-number>123</account-number> <company-name></company-name> <email></email> <fizzid></fizzid> <first-name>John</first-name> <phone-1>5551114444</phone-1> <phone-2>5553334444</phone-2> <phone-3></phone-3> <phone-1-label>home</phone-1-label> <phone-2-label>cell</phone-2-label> <phone-3-label>work</phone-3-label> <id>12</id> <last-name>Doe</last-name> </customer> <customer> ... </customer> </customers> |
/fizz/customers/12.xml |
<?xml version="1.0" encoding="UTF-8"?> <customer> <account-number>123</account-number> <company-name></company-name> <email></email> <fizzid></fizzid> <first-name>John</first-name> <phone-1>5551114444</phone-1> <phone-2>5553334444</phone-2> <phone-3></phone-3> <phone-1-label>home</phone-1-label> <phone-2-label>cell</phone-2-label> <phone-3-label>work</phone-3-label> <id>12</id> <last-name>Doe</last-name> </customer> |