iTango Restful API Service

Connect your software to iTango with its simple API.


Overview

RESTful systems communicate over the Hypertext Transfer Protocol with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) used by web browsers to retrieve web pages and send data to remote servers. The iTango API uses HTTP verbs and a RESTful endpoint structure.

What I need?

  • About 15 minutes
  • A favorite text editor or IDE
  • A API-TOKEN code password (you have to register yourself and then request the API TOKEN by this link)
  • A Unix-Shell to test the commands

Authentication

This first version of the Restful service uses a "api-token" code that you can request by the contact form. Please take care of your api-token. If you think the key has been compromised, you can request a new token by the contact form.

The "client login" is delegated to the api-token that contacts the server to request the records. Every request must include it. If there is an error with the API-TOKEN the response will be:

"status":"fail","code":"999","error":"Invalid API Token"

Event Methods

iTango provides a restful service that helps you to get, insert, delete one or more tango events by a simple request from a web browser, or a system call. These are the main features:

  • Get last events
  • Get the user events
  • Insert a new event
  • Delete a specific event

Latest Events

All the events on the iTango service are imported by a standard procedure by Google Calendar, Facebook Events and/or manually. The content of each event is handled by the owner and the content is converted into an html code.

ACTION:

- get the new and active events

URL:

- http://itango.it/v1/events/

ARGUMENTS:

  • (string) API-TOKEN

REQUEST EXAMPLE:

$ curl -i -H "Accept: application/json" http://itango.it/v1/events/API-TOKEN


You will get a Json string like:

"data":["id":"23","title":"Milonga-del-CUS \u003E La Milonga del Sabato \u003E dalle 21:00 alle 2:30","start":"2014-12-06 21:00:00","end":"2015-06-06 07:00:00","address":"CUS - Cittadella Universitaria, via Santa Sofia n. 68 - Catania"]

Create a new Event

In order to create a new tango event you have to call a POST method and you have to send the following arguments.

ACTION:

- create a new tango event

URL:

- http://itango.it/v1/events/language/

ARGUMENTS:

  • (string) API-TOKEN
  • (string) Title
  • (integer) Category ID
  • (integer) Country ID
  • (datetime) Start
  • (datetime) End
  • (string) Content
  • (string) Address
  • (boolean) Visible
  • (boolean) Showonlist
  • (string) Contact

For instance: if we want to add a new visible/public tango event at Suipacha 384, Buenos Aires Argentina with a title "A Pura Milonga" that starts at 17-01-2015 19:30 and it ends at the 18-01-2015 03:00 with this description: "Tango at Buenos Aires"

$ curl -i -H "Accept: application/json" -X POST -d "title=A Pura Milonga&category_id=2&start=2015-01-17 19:30&end=2015-01-18 03:00&country_id=82&contact=+39.123123123&visible=1&showonlist=1&content=Tango at Buenos Aires&address=Suipacha 384, Buenos Aires, Argentina" http://itango.it/v1/events/API-TOKEN


If there is an error and the request has been not executed, the response will be:

{"data":[],"error":{"title":{"isEmpty":"Value is required and can't be empty" ...


Executing the above command you will get this result string with the ID of the event:

"data":"id":"10","title":"A Pura Milonga","start":"2015-01-17 19:30:00","end":"2015-01-18 03:00:00","address":"Suipacha 384, Buenos Aires, Argentina"

Extra Data

If you need to get the country list or tango category list you have to call and cache the following methods.

Get the languages

In order to get the language list data you have tocall and cache the result of this method.

ACTION:

- get all active languages

URL:

- http://itango.it/v1/events/language/

ARGUMENTS:

  • (string) API-TOKEN

REQUEST EXAMPLE:

$ curl -i -H "Accept: application/json" http://itango.it/v1/language/API-TOKEN

 

Get the country

In order to get the country list data you have tocall and cache the result of thi method.

ACTION:

- get all active countries

URL:

- http://itango.it/v1/events/country/

ARGUMENTS:

  • (string) API-TOKEN

REQUEST EXAMPLE:

$ curl -i -H "Accept: application/json" http://itango.it/v1/country/API-TOKEN

Get the tango category

In order to get the country list data you have tocall and cache the result of this method.

ACTION:

- get all active tango categories

URL:

- http://itango.it/v1/events/category/

ARGUMENTS:

  • (string) API-TOKEN

REQUEST EXAMPLE:

$ curl -i -H "Accept: application/json" http://itango.it/v1/category/API-TOKEN

Restful errors

If the restful service found an error, you will get this message:

{"data":[],"error":{"title":{"isEmpty":"Value is required and can't be empty" ...

PHP Sample

You can integrate into your own Web Project or Android or iOS APP the iTango project. Here some snippets of code:

https://gist.github.com/shinesoftware/60b58efee18c83431720 (Create a new tango event)