Using the API

Using the API

The Upcoming.org REST API is available for non-commercial application developers to build cool stuff by providing easy access to all public information stored in Upcoming's databases.

The set of methods provided allow for manipulating and extracting data from Upcoming.org with simple HTTP GET and POST requests in a RESTful fashion.

Using the Upcoming.org REST API typically occurs either through a user-contributed Client Library, or by manually constructing the appropriate GET or POST request to the proper API gateway.

Client Libraries

Client libraries take care of all of the heavy communications lifting, XML parsing, REST handling, etc., and let you just take advantage of the features that the Upcoming API has to offer.

Client libraries are the recommended way to use the Upcoming.org API. A current list of client libraries is maintained at Language-specific Libraries.

See also: Upcoming with PHP Tutorial

Manual REST

If you've decided to connect directly to the Upcoming.org API, this page will contain useful information, as well as user-contributed tips and tricks that might be helpful in your quest.

See also: Example REST URLs

Testing

For testing your connectivity to the Upcoming.org API, we recommend the use of cURL to construct test responses and requests to the API. You can use the --trace-ascii parameter to see all of the HTTP communication that goes on, which is particularly useful if you're attempting to construct POST communications.

Please check: API POST Method Tips for tips on how to get your POST API requests working!

Versioning

A planned upgrade to the API is to allow a client library to pass a version number to the gateway to interact with versioned, separately documented API methods. This will be provided in the future. For now, examine the version attribute returned in the response node to verify that the response version matches the version you expect.

Additions / Requests

We want you to develop as much cool stuff as possible with the Upcoming API. If you run into problems, or can't find a way to do something effectively, please let us know! We have a pretty quick turnaround time with bugs and reasonable enhancement requests. Use the Bug Reports page or the Suggestion Box to drop off your requests.