How to Access the Tickspot API with cURL

VIA Studio's Mark Biek recently demonstrated the benefits of using cURL to bypass the typical code writing exercise needed to pull app data. cURL is a utility that's commonly used by developers to interact with Web servers from the command line of an operating system like Unix, Linux, and Mac OS X. Because of how it can send and receive Web requests, it is ready-made for poking around with Web-based APIs. Biek displayed cURL in action by accessing the Tickspot API, a handy time-tracking tool. Accessing Tickspot through its API allows users like VIA Studio to build apps on top of Tickspot (e.g. custom reporting, estimation tools, etc.).

Accessing an API via command-line is as simple as three lines of code:


curl -u "email@domain.com:password" -H "User-Agent: TickTesting (email@domain.com)" https://www.tickspot.com/api/v2/roles.json

The first part authenticates the call to the API using email address as the user ID and a password. In other words, in this example, Biek uses what is often referred to as *Basic Authentication*. 

The next part specifies a particular *User Agent* to include in the HTTP header of the request (all Web requests have an HTTP header that go with them).  Although a header goes with every request, the data that must be included in the header varies from API to API.  The next part of the request takes the form of: 

NameofApp (tick-user-email-address).

The example above returns a JSON array. The response includes all Tickspot subscriptions for the user as well as an *Authorization Token* to be used for future requests. Be aware, the response should only include one company, but it's possible to return multiple results: 


[

{

“subscription_id”: 12345,

“company”: “My Company”,

“api_token”: “nDRE9v2SwkEE6PLfyJhmk3BrnDRE9v2S"

}

]

To call other endpoints, you need only the *subscription_id* and the *api_token* listed above. To demonstrate, Biek called a lists of projects for the company:


curl -H "Authorization: Token token=nDRE9v2SwkEE6PLfyJhmk3BrnDRE9v2S" -H "User-Agent TickTesting (email@domain.com)" https://www.tickspot.com/12345/api/v2/projects.json

This line shows the passing of token and app data in the header.  The last part of the request is Tickspot's endpoint and it is not uncommon for the ".json" extension to be included with endpoints that can return data in multiple formats (json, xml, csv, etc).  If an API allows extensions like ".json", it is typically a means of specifying how you want the response formatted.

Biek notes that calling most endpoints will only return 100 results. More data can be returned by altering pagination parameters (e.g. page=2, page=3, etc.). The API returns an empty response when all data has been retrieved.

Calling APIs via cURL is as simple as the above listed example. Calling other endpoints works in the exact same manner. To stick with the Tickspot example, check out the docs on Github for more endpoints.

Original Article

THE TICKSPOT API AND COMMAND-LINE CURL

Eric Carter Eric the founder of Dartsand and Corporate Counsel for a specialty technology distributor. He is a frequent contributor to technology media outlets and also serves as primary legal counsel for multiple startups in the Real Estate, Virtual Assistant, and Software Development Industries. Follow me on Google+
 

Comments