Login or Register

API Docs: V2 API

Overview

Joind.in is offering a HTTP web service to give clean, robust access to the data contained in the application to consuming devices. It follows a RESTful style, is available in HTML and JSON formats, and uses OAuth v1.0a for authentication where this is needed (all data publicly visible on the site is available via the API without authentication). Hyperlinks are provided the responses to allow you to easily locate related data. This document gives information about the functionality of the API and how to use it.

Global Parameters

There are a few parameters supported on every request:

  • verbose: set to yes to see a more detailed set of data in the responses. This works for individual records and collections.
  • start: for responses which return lists, this will offset the start of the result set which is returned. The default is zero; use in conjuction with resultsperpage
  • resultsperpage: for responses which return lists, set how many results will be returned. The default is currently 20 records; use with start to get large result sets in manageable chunks
  • format: set this to html or json to specify what format the response should be in (preferably use the Accept Header, alternatively you can pass this param)

Data Formats

The service currenty supports JSON and HTML only, although these can very easily be expanded upon in future. The service will guess from your accept header which format you wanted. In the event that this is not behaving as expected, simply add the format parameter to specify which format should be returned.

If you want to use the data provided by this API from JavaScript, we offer support for JSONP. To use this, request json format data and pass an additional callback parameter; the results will be the usual JSON but surrounded with the function you named.

Where there are links to other resources, and for pagination, you will find those links as part of the response. The pagination links look something like this:

Authentication

You only need to authenticate if you're adding or editing data (including comments) or want to access private data. For most operations, particularly just retrieving information, authentication is not required.

This API uses OAuth2. To authenticate you will need the following:

  1. Every app must first register for an API key and give the callback that they will use to send users to. To register an API key, sign in to joind.in and visit: https://joind.in//user/apikey. These are associated with your user account, you can have as many as you like and you can delete them at any time.
  2. When you want a user to grant you access to their data, send them to: https://joind.in//user/oauth_allow with the following query variables on the URL:
    • api_key The key you registered for in step 1 (the secret isn't currently used)
    • callback The callback URL to send the user to afterwards. This can be a device URL and it must match the URL you registered in step 1 (exactly match)
    • state (optional) Whatever you pass in here will be passed back with the user when we redirect them back to you. Use it however you like
  3. When the user is sent to the redirect URL, it will contain one additional parameter: access_token. Capture this and store it - this is a per-user token.
  4. To make requests with access to that user's data, add the access token into an authorisation header. The format should be:
    Authorization: OAuth [access_code]

    5. If you have any questions or problems, just let us know, this is new functionality and feedback is more than welcome.

    Service Detail

    Examples shown in HTML format. The JSON response holds identical data, passed through json_encode rather than pretty-printed

    Request: GET /

    try it

    This is your starting point and will show you where you can go:

    Request: GET /events

    Request: GET /events/[id]

    try it

    Shows a list of events, with a variety of filter/sorting behaviour supported (see above entry). The default is all events sorted by date descending. As ever, you can use the links to get to other information, and the verbose, start, requestsperpage and format parameters as you need to. The "attending" field will be set to 1 when there is an authenticated user who is marked as attending this event.

    Each result looks something like this:

    Request: GET /events/[id]/talks

    Request: GET /talks/[id]

    try it

    Following the link to the talks for an event gives a list. The format, verbose, start and requestsperpage parameters are valid. Each talk entry will look something like this:

    • talk_title: Estimation, or "How To Dig Your Own Grave"
    • talk_description: Clients need to know how much a project will cost. Waterfall development is always late and over-budget. Agile development is done when it's done. You're left with estimates that you know are too low and then you squeeze them anyway. It shouldn't be this way. We'll look at how this happens, early warning signs, ways out and ways of avoiding it in the first place.
    • slides_link: http://merewood.org/estimation-or-how-to-dig-your-own-grave/
    • language: English - UK
    • start_date: 2012-04-13T09:50:00+01:00
    • average_rating: 5
    • comments_enabled: 1
    • comment_count: 12
    • speakers:

    Request: GET /talks/[talk_id]/comments

    Request: GET /talks/[talk_id]/comments/[comment_id]

    The talk comments (note that event comments are a different thing) include a rating and comment, and if the comment was made by a logged-in user, a link to their user account. The format, start and requestsperpage parameters are valid, and the record for each comment looks something like this:

    try it

    Request: GET /events/[event_id]/comments

    Request: GET /events/[event_id]/comments/[comment_id]

    The comments show who made the comment and their comment and rating. The format, start and requestsperpage parameters are valid, and the record for each comment looks something like this:

    try it

    Request: GET /users/[user_id]

    The user resource is available where the user is the speaker for a talk, a host of an event, and where they have left comments logged in as themselves. It includes links to the talks given by this user and the events they attended

    try it

    Request: GET /users/[user_id]/attended

    A list of all the events a user has been to (where they have marked themselves as attending the event). The output format is exactly as the other events

    try it

    Request: GET /users/[user_id]/talks

    All the talks given by this user, in the same format as the other talk results

    try it

Sign in

Or login via these services:
Sign in with twitter

Sign in with Facebook

Need an account? Register now!
Forgot Password

Combell
Cloud server hosting by Combell

Submit your event

Know of an event happening? Let us know! We love to get the word out about events the community would be interested in and you can help us spread the word!

Submit your event!

Events | Talks | Search | About | Help | Blog | API | Contact
Cloud server hosting by Combell Combell      © Joind.in 2012