Introduction to the Syncd API
Syncd exposes most of its functionality via an Application Programming Interface (API), which enables developers to build applications that interact with Syncd.
The Syncd API adheres to the REST principles as closely as possible. Resources, such as jobs, users and time entries, each have a unique URI. These resources are controlled using the primary HTTP verbs: GET, POST, PUT AND DELETE. Data is returned in XML format.
Security and Authentication
The Syncd API uses HTTP basic authentication to identify users. Users are identified with the same user names and passwords that are used by the web interface. Of course, users have the same permissions to view and modify data using the API as they do using the web interface.
The API requires the use of the secure HTTPS protocol to transmit all data, including authentication credentials, from client applications to Syncd's servers. This ensures that Syncd's API is every bit as secure as its web interface.
Using a Web Browser
Perhaps the easiest way to try out the API is with your web browser, which issues an HTTP GET request whenever you type in a URL. Certain browsers are better than others for displaying XML data - we recommend using Firefox or Camino for a quick test of the API. Just browse to any resource in your Syncd account, such as a job, and then append
.xml to the URL. After a being prompted for your user name and password, you should see an XML representation of that resource.
For example, we can browse to the following URL for our sample "artworks" account (please test a similar request from your own account):
After entering a valid user name and password, this yields the following result:
<job> <id type="integer">95</id> <job-type-id type="integer">8</job-type-id> <parent-id type="integer">94</parent-id> <name>Irises</name> <code nil="true"/> <description>Remove gum from corner of painting.</description> <url nil="true"/> <active type="boolean">true</active> <effectively-active type="boolean">true</effectively-active> </job>
cURL is a command line tool included with many operating systems. If you do not have cURL installed, you can download it here. cURL provides a more thorough means of testing the API than your browser, since it makes it easy to issue requests with verbs other than GET.
The following cURL request returns the same XML as the sample above (note: the fake username and password prevent this example from returning successfully):
curl -u username:password -H 'Accept: application/xml' 'https://artworks.syncd.com/jobs/95.xml' -v
You may find it helpful to run cURL in verbose mode in order to see the full details of both your requests and Syncd's responses. Verbose mode is enabled by including the
The following examples illustrate the use of cURL to create, read, update and delete data (commonly referred to as CRUD operations).
Data should be requested using the HTTP verb GET. Because GET is the default verb for most HTTP clients, including cURL, it is probably not necessary to explicitly specify the GET verb with your data requests.
It is recommended that you specify the header
'Accept: application/xml' to indicate that your application expects XML to be returned. In the future, Syncd may return data in multiple formats, so specifying this header guarantees that your application will always receive XML results.
A status of
'200 OK' will be returned with a successful request to read data.
Working with Arrays
We've already seen an example of using cURL to return a single resource's data (see above). Syncd also provides a number of methods which return arrays of resources. For example, the following request returns all the jobs in our sample account:
curl -u username:password -H 'Accept: application/xml' 'https://artworks.syncd.com/jobs.xml' -v
This request returns multiple
<job> tags wrapped in a single
<jobs> tag. Note the
end attributes on the
<jobs type="array" total="18" start="1" end="18"> <job> <id type="integer">88</id> <job-type-id type="integer">7</job-type-id> <parent-id type="integer" nil="true"/> <name>American UFO Assoc.</name> <code nil="true"/> <description nil="true"/> <url nil="true"/> <active type="boolean">true</active> <effectively-active type="boolean">true</effectively-active> </job> <job> ... </job> ... </jobs>
Syncd follows this same convention for all methods that return arrays of resources. Each request can return a maximum of 1000 array members, so please check the
end attributes carefully.
Specific records can be requested with the
start and / or
end parameters. For example, the following request returns the first 50 jobs:
curl -u username:password -H 'Accept: application/xml' 'https://artworks.syncd.com/jobs.xml?start=1&end=50' -v
Including Related Records
You can improve your application's performance by minimizing the number of API calls it makes. In order to help, we've designed many methods to accept an optional
include parameter, which allows related records to be returned with a single request.
For instance, the following request returns all job assignments, as well as any associated user, user group and job records:
curl -u username:password -H 'Accept: application/xml'
In order to include created and updated timestamps for records, specify
curl -u username:password -H 'Accept: application/xml' 'https://artworks.syncd.com/jobs.xml?include=timestamps' -v
The API documentation explains the optional
include parameters allowed for each API method. An exception is
include=timestamps, which is allowed for all methods that return data.
Writing data should be done with the appropriate HTTP verb: POST to create resources, PUT to update resources, and DELETE to delete resources.
As when reading data, it is recommended that you specify the header
'Accept: application/xml' to indicate that you'd like data returned as XML. Furthermore, specify the header
'Content-Type:application/xml' whenever including XML data with your request.
Use the POST verb to create resources. The following request will create a new job named 'Test' in our sample account:
curl -u username:password -X POST -H 'Accept: application/xml' -H 'Content-Type:application/xml' 'https://artworks.syncd.com/jobs.xml' -d '<job><name>Test</name><description>Only a test</description></job>' -v
A status of
'201 Created' will be returned with a successful request to create a resource. In addition, the newly created resource's data (including its new id) will be returned.
Use the PUT verb to update resources. The following request will change the name of the above job:
curl -u username:password -X PUT -H 'Accept: application/xml' -H 'Content-Type:application/xml' 'https://artworks.syncd.com/jobs/536.xml' -d '<job><name>New name</name></job>' -v
A status of
'200 OK' will be returned with a successful request to update a resource.
Use the DELETE verb to delete resources. The following request will delete the job just created above:
curl -u username:password -X DELETE -H 'Accept: application/xml' 'https://artworks.syncd.com/jobs/536.xml' -v
A status of
'200 OK' will be returned with a successful request to delete a resource.
Whenever possible, the appropriate HTTP status codes will be returned to indicate whether Syncd could successfully respond to a request. Here are some of the most common status codes that you may encounter:
200 OK- Your request to retrieve, update or delete data was successful.
201 Created- A resource was successfully created.
304 Not Modified- See the discussion of ETags below.
401 Unauthorized- You are not authorized to perform the requested operation.
404 Not Found- The requested resource could not be found.
422 Unprocessable Entity- Your request could not be processed. An explanation should be returned as data.
ETags are returned with all responses to allow clients to make conditional GET requests. Use ETags to improve your application's performance and save bandwidth by caching data in your client and only retrieving data when it's changed.
All responses to GET requests include an
ETag in the header. For instance:
If you cache this ETag along with the data in your client, you can include it in the
If-None-Match header of subsequent GET requests. For instance:
If the data hasn't changed, Syncd will return the status
304 Not Modified.
However, if data has changed, Syncd will return a full response along with a new ETag in the header.
Data types other than strings are specified with the
type attribute. The following data types are used by this API:
integer- Every resource is uniquely identified with an integer ID.
date- A date with a format of YYYY-MM-DD. For example,
2008-01-21is January 21st, 2008.
datetime- A date and time format of YYYY-MM-DDThh:mm:ssZ, which includes the time zone offset (Z). For example,
2008-01-06T16:01:00-05:00is 4:01pm on January 6, 2008 UTC-05.
2008-01-06T16:01:00Zis also 4:01pm on January 6, 2008, but is UTC. Times are almost exclusively returned in UTC, with the notable exception of time entry start / end times.
Syncd supports many customizations, including how work is structured, the terminology used for classifications, and which features are enabled for each account. Although the API uses internal names such as jobs and activities, it's important to use the terminology particular to each account when building an interface to Syncd. Please review Account Information for more details.
User Rights and Preferences
A user's rights control what they can view and modify within their account. For instance, only Job Managers have the right to add and modify jobs. This documentation specifies the rights, if any, needed to perform actions.
Users can customize Syncd with their own preferences, such as numeric formats, the first day of the week, etc. These preferences should be respected when developing your application's interface.
This concludes the introduction to Syncd API. If you have any questions or feedback, please email us at support( AT )syncd( DOT )com.
Please continue to read the detailed documentation for the Syncd API.