Developer Guide for JSON Endpoint

Intro

The JSON Endpoint makes all agenda data available at a single endpoint. The data is returned in one document, rather than different endpoints for different data types.

To create an endpoint a new ‘JSON’ publication needs to be configured by an event manager, this will generate a unique URL for the event.

If the event manager has asked you for answers to the ‘Webhook’ and ‘How should related items be referenced’ then review the ‘Webhook’ and ‘Schema Choice’ documentation below.

Requesting the data

To request the event data perform a GET to the URL you have been provided by the event manager. This URL is unique for each publication. The endpoint may require credentials using HTTP Basic Auth depending on the settings in the configuration.

Depending on your event you will either receive a 200 with the full event data, or a 302 redirect with a temporary url for the location of the data. Note that the destination of this 302 will change for each request and will expire. You should begin your request with the initial url starting with http://api.lineup.ninja each time.

Refreshing the data

The event manager will make changes to their content over the course of time. To receive the changes you can either poll every 5 minutes, or integrate the webhook to receive an instant notification that new event data is ready.

If you are polling the event data be sure to schedule the removal of the polling after the event has completed.

When content is removed from an event, eg a speaker pulls out, you will not receive an explicit notification. Instead, because the document contains the full set of data for the event, you should treat that absence of a previously existing object as a request to delete that object.

Profile Photos / Company Logos

Profile Photos (aka headshots) are included at these sizes

• 128x128
• 256x256
• 512x512
• 1024x1024

Company Logos are included with the original aspect ratio and scaled to fit the same sizes as the headshots.

Files

The event manager can choose to include additional links to files attached to speakers, sessions, labels, locations, resources and tracks.

The included links are unique to each publication for the event, if the event manager deletes the publication the links will cease to operate.

Note that speaker profile photos and company logos do not appear as ‘files’, they have their own property of ‘headshot’ and ’logo’. They are always included if the event has the data.

Schema Choice

The JSON feed is available two different structures. They differ by how related data is referenced.

For example with an event with two speakers, Alice and Bob, and one session Keynote. The feed can be presented in one of these two ways.

References By ID

If you choose ‘References By ID’ then related objects are referenced by their id only. For example:

Speakers:

[
    { id: 123, firstName: 'Alice', sessions: [ 125 ] }
    { id: 124, firstName: 'Bob', session: [ 125 ] }
]

Sessions: [

    { id: 125, name: 'Keynote', contributors: [ 123, 124 ] }
]

This structure is recommended if you are going to be importing the data into a database or other denormalized structure.

See References By Id Schema for the full schema.

Embedded References

If you choose ‘Embed The Referenced Items’ the structure will look like this

Speakers:

[
    { id: 123, firstName: 'Alice', sessions: [
        { id: 125, name: 'Keynote'}
    ] }
    { id: 124, firstName: 'Bob', sessions: [
        { id: 125, name: 'Keynote'}
    ] }
]

Sessions:

[
    { id: 125, name: 'Keynote', contributors: [ 
        { id: 123, firstName: 'Alice' }
        { id: 124, firstName: 'Bob' }
     ] }
]

This structure is recommended if you want to use the feed ‘as is’, i.e. to be easily reference all speaker data when looking at a particular session.

See Embedded Reference Schema for the full schema.

Selecting the schema mode

To switch between these two modes ask the event manager to edit the configuration and set the value of ‘How should related items be referenced’ to either ‘References By ID’ or ‘Embedded References’.

Webhook

If configured Lineup Ninja will call a webhook after a successful publish of the event. The webhook is called as a POST with this body:

{
    /**
     * The UUID of the event
     */
    eventId: string;
    /**
     * The name of the event
     */
    eventName: string;
    /**
     * The timestamp for the publication. You can use this to deduplicate calls to the webhook
     * It is in epoch time with milliseconds (A javascript timestamp)
     */
    publicationTimestamp: number;
    /**
     * The UUID for the integration. The customer may wish to configure multiple integrations per event,
     * for example to different staging and production events. this ID can uniquely identify them
     */
    integrationId: string;
}

To create the webhook ask the event manager to edit the configuration to set the value of ‘Webhook URL to call after publishing’ to your desired URL.

Still can’t find what you’re looking for? Email support@lineupninja.com and one of the team will get back to you as soon as possible.​​​​​