Gininet

Gininet API v1.0 (server side)

Introduction

This is the first part of how a Gininet event works: server side. These requests normally initiated by your application's server side to our API endpoint.

API endpoint

To send request to Gininet API, you need to use the following URL:

https://api.gininet.com

API protocol

Requests

API requests must be sent using SSL to the API endpoint. API access tokens must be sent as an HTTP header with the name "apitoken" and its value is your API access token.

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d 'parameters-as-stringified-json-object' https://api.gininet.com/project/create

Responses

Every request generates a response with HTTP 200 status code, unless the requested URL doesn't exist which is as expected, HTTP 404.
If there's an error, the system sends a json object with an 'error' field that contains the error message.

{
"error": "Invalid access token"
}

If the call was successful and the procedure doesn't have a return value, it returns a json object with a 'success' field that contains the boolean value 'true'

{
"success": true
}

If the call was successful and the procedure has a return value, it returns a json object with the procedure's returned value

{
"id": "abcdefghijklmnopqrstuvwxyz"
}

API calls

Account

Get account balance

Your Gininet account balance

Account calls require account level API access token.


Get account balance

The function returns the current account balance and the available balance.

available account balance = total account balance - pending expenses

We require you to deposit the full service charge for your event. 30 minutes after the event ended we calculate the actual cost of the event based on the number of participants. Then we make the remaining amount available again.

https://api.gininet.com/account/balance

Parameters:

No parameters

Positive response:

Name Type Description
balance Number The current account balance
available Number The available account balance

Negative response:

Name Type Description
error String The error description

Example

Request

curl -X POST -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' https://api.gininet.com/account/balance

Response

{"balance":100, "available":75.24}

{"error":"Account access token is required"}

Project

List, create, search, edit and remove projects.

All of your Gininet assets belong to a project. You can create multiple access token to a project that gives access to the assets of that project only.

Project calls require account level API access token.


Create a project

The function creates a new project.

https://api.gininet.com/project/create

Parameters:

Name Type Description
name (*) String The name of your new project
description String The description of your new project

Positive response:

Name Type Description
id String The id of your new project

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"name":"my-first-project"}' https://api.gininet.com/project/create

Response

{"id":"11bd834c348a991"}

{"error":"You have a project with this name. The name of your new project must be unique."}


Edit a project

The function modifies a project's name and/or description.

https://api.gininet.com/project/edit

Parameters:

Name Type Description
id (*) String The id of your existing project
name String The new name of your project
Either this or the description field is required
description String The new description of your project
Either this or the name field is required

Positive response:

Name Type Description
success Boolean Indicating a successful call if this is set

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"name":"my-first-edited-project","id":"11bd834c348a991"}' https://api.gininet.com/project/edit

Response

{"success":true}

{"error":"Account access token is required"}


Remove a project

The function removes a project and all related assets. The procedure can not be undone.

https://api.gininet.com/project/remove

Parameters:

Name Type Description
id (*) String The id of your existing project

Positive response:

Name Type Description
success Boolean Default response if call was successful

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"id":"11bd834c348a991"}' https://api.gininet.com/project/remove

Response

{"success":true}

{"error":"Account access token is required"}


Search for or list projects

The function searches for a project that contains the searched text in its name. Use this function to list your projects too with no parameters or to get a project by its id by using an 'id' field (see below).

https://api.gininet.com/project/search

Parameters:

Name Type Description
query String The text that you search for.
id String The id of the project that you request.

Positive response:

Name Type Description
projects Array The list of project objects containing the searched text or the list of your projects if the query parameter was omitted

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"query":"first"}' https://api.gininet.com/project/search

Response

{"projects":[{"id":"11bd834c348a991", name:"my-first-edited-project", createdat:"2017-01-01T18:00:00.000Z"}]}

{"error":"Invalid token"}

API tokens

List, create, search, and remove access tokens to your projects.

You must create one API access token to each of your project in order to be able to use it.

The API token has access to the configured project only.

Apitoken calls require account level API access token.


Create a new API token

The function creates a new api token. Requires an API token with account access level.

https://api.gininet.com/apitoken/create

Parameters:

Name Type Description
name (*) String The name of your new project
project (*) String The ID of the project which this api token will manage

Positive response:

Name Type Description
id String Your new, project-level API token

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"project":"11bd834c348a991"}' https://api.gininet.com/apitoken/create

Response

{"id":"848b73ac8778372"}

{"error":"Account access token is required"}


Revoke an API token

The function revokes an api token. Subsequent calls with this token will return an invalid token message.

https://api.gininet.com/apitoken/remove

Parameters:

Name Type Description
id (*) String The id of your existing api token

Positive response:

Name Type Description
success Boolean Indicating successful procedure

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"id":"848b73ac8778372"}' https://api.gininet.com/apitoken/remove

Response

{"success":true}

{"error":"Account access token is required"}


Search for API tokens

The function returns the list of API tokens.

https://api.gininet.com/apitoken/search

Parameters:

Name Type Description
project String The id of the project to list the API tokens of

Positive response:

Name Type Description
apitokens Array The list of the API tokens.

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"project":"11bd834c348a991"}' https://api.gininet.com/apitoken/list

Response

{"apitokens":[{"id":"848b73ac8778372", createdat:"2017-01-01T19:00:00.000Z", "project":"11bd834c348a991"}]}

{"error":"Account access token is required"}

Events

Create, edit, remove and search events


Create a new event

The function creates a new event.

https://api.gininet.com/event/create

Parameters:

Name Type Description
name String The name of your new event. This field is to identify the event.
desc String The description of your new event.
project (*) String The ID of the project which this event will belong to.
starttime (*) String When your event starts in ISO 8601 date-time format
endtime (*) String When your event ends in ISO 8601 date-time format
type (*) String Type of the event. One of "SB", "IB", "CB". See event types for more details
ticketav () Number Depending on the event type, you need to add at least one ticket type. One or more of "AV", "TC", "NI" with values of how many tickets you require. Omitting fields or 0 valued fields result in those ticket types will be unavailable.
tickettc () Number Depending on the event type, you need to add at least one ticket type. One or more of "AV", "TC", "NI" with values of how many tickets you require. Omitting fields or 0 valued fields result in those ticket types will be unavailable.
ticketni () Number Depending on the event type, you need to add at least one ticket type. One or more of "AV", "TC", "NI" with values of how many tickets you require. Omitting fields or 0 valued fields result in those ticket types will be unavailable.

Positive response:

Name Type Description
id String The id of your new event

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"name":"my-first-event", "starttime":"2017-08-18T11:00:00.000Z", "endtime":"2017-08-18T12:00:00.000Z", "type":"SB", "ticketni":100, "project":"11bd834c348a991"}' https://api.gininet.com/event/create

Response

{"id":"546e98facb9422cc"}

{"error":"Insufficient funds."}


Edit an event

The function edits the event name and/or description. If you need to edit any other attributes of an event please remove this event if possible and create another one

https://api.gininet.com/event/edit

Parameters:

Name Type Description
id (*) String The id of your existing event
name () String The new name of your event. At least one of the name or description fields must present in a request
desc () String The new name of your event. At least one of the name or description fields must present in a request

Positive response:

Name Type Description
success Boolean Indicating successful procedure

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"id":"546e98facb9422cc", "name":"my-first-edited-event"}' https://api.gininet.com/event/edit

Response

{"success":true}

{"error":"Invalid request. Missing parameter(s)"}


Remove an event

The function removes an event. You are able to remove an event up to half an hour before it starts.

https://api.gininet.com/event/remove

Parameters:

Name Type Description
id (*) String The id of the event

Positive response:

Name Type Description
success Boolean Indicating successful procedure

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"event":"546e98facb9422cc"}' https://api.gininet.com/event/remove

Response

{"success":true}

{"error":"Unable to remove. The event has already started."}

Search for events

The function searches events by starttime or name, lists past events or lists upcoming events.

https://api.gininet.com/event/search

Parameters:

Name Type Description
name String The text to search in the events' name.
starttime ISO8601 date The events at or after this starttime.
past Boolean To list past events (endtime < now)

Positive response:

Name Type Description
events Array The resulting array of event objects

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"past":true}' https://api.gininet.com/event/search

Response

{"events":[{"id":"546e98facb9422cc", "name":"my-first-edited-event", "starttime":"2017-08-18T11:00:00.000Z", "endtime":"2017-08-18T12:00:00.000Z", "type":"SB", "ticketni":100}]}

{"error":"Invalid API token"}

Tickets

Create, remove access tokens to a Gininet event and get ticket stats


Create a ticket

The function creates one or more new ticket(s)

https://api.gininet.com/ticket/create

Parameters:

Name Type Description
event (*) String The id of your event.
type (*) String The type of the ticket you request. One of "P" for presenter, "NI" for non-interactive, "TC" for text-chat and "AV" for audio-video interactive
amount (*) Number How many tickets your request (same event, same type).

Positive response:

Name Type Description
tickets Array The array of ticket objects [{"id":"ticket-id", "batch":"221d8914ac1648b78454554a41f64bb3"...}]

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"event":"546e98facb9422cc", "type":"P", "amount":1}' https://api.gininet.com/ticket/create

Response

{"tickets":[{"id":"a452-bc8e-f2e6-9830-d89e-a71c", "batch":"221d8914ac1648b78454554a41f64bb3"}]}

{"error":"Unable to create ticket. Maximum number of tickets of this type reached"}


Remove a previously requested ticket

The function invalidates/removes a previously requested ticket

https://api.gininet.com/ticket/remove

Parameters:

Name Type Description
ticket (*) String The id of your ticket.

Positive response:

Name Type Description
success Boolean Indicates successful procedure if true

Negative response:

Name Type Description
error String The error description

Example

Request

curl -H 'Content-Type: application/json' -H 'Apitoken: your-api-access-token' -d '{"ticket":"a452-bc8e-f2e6-9830-d89e-a71c"}' https://api.gininet.com/ticket/remove

Response

{"success":true}

{"error":"Invalid ticket id"}