UfoSeti API description
What API is for?
Application Programming Interface (API) is a specification intended to be used as an interface by software components to communicate with each other. UfoSeti presents own API for everyone, without any restrictions.
What it provides
UfoSeti provides an open access to the database for third parties. Service includes reading and writing to the database with POST request. Currently two formats are supported: JSON and XML. General statistics available as well.
Database status
UfoSeti API provides general information about current database status. For retrieveing the state information a following request is suppotered:
format - n expected output format. Possible options: JSON, XML. Default is: JSON.
countries - fulter messages with countryен codes. Expected format is ISO 3166-1 alpha-2 (two caracters code),all the codes should be listed with comma with no space. This parameter is optional and can be ignored.
JSON request for the general database status
Request
http://www.ufoseti.org/api/v1/messages/status.json
Responce
{
statistics: {
total_messages: 345,
last_message_id: 372,
last_message_posted_at: 2012-03-30T05:43:25Z
}
}
XML request for the general database status
Request
http://www.ufoseti.org/api/v1/messages/status.xml
Responce
<?xml version="1.0" encoding="UTF-8"?>
<statistics>
<total-messages type="integer">345</total-messages>
<last-message-id type="integer">372</last-message-id>
<last-message-posted-at type="datetime">2012-03-30T05:43:25Z</last-message-posted-at>
</statistics>
JSON request return the database status for stecific country
Request
http://www.ufoseti.org/api/v1/messages/status.json?countries=ru,ee,lv,lt
Responce
{
statistics: {
total_messages: 115,
last_message_id: 321,
last_message_posted_at: 2011-11-25T05:43:25Z
}
}
JSON request with no messages matching
Request
http://www.ufoseti.org/api/v1/messages/status.json?countries=za
Responce
{
statistics: {
total_messages: 0
}
}
Specific message
UfoSeti API provides along with general statistics an opportunity to retrieve a details for certain message. In order to do so, client allpication is expected to send the following request:
http://www.ufoseti.org/api/v1/messages/1.(:format)?(locale=:locale)
where parameters are:
- format - an expected output format. Possible options: JSON, XML. Default is: JSON.
- locale - translation locale the message is expected to be returned. The paramater expected to be sent in ISO 3166-1 alpha-2 (two caracter code). This is an optional parameter, Default is : en.
JSON request for message in specific locale
Request
http://www.ufoseti.org/api/v1/messages/7.json
Responce
{
message: {
id: 7,
observed_at: 2010-01-14T015:23:25Z,
place: 'Marjamagi Village',
note: 'Additional Info',
comment: 'Moderator\'s comment',
direction: 'North',
shape: 'Triangle',
investigation_status: 'Unconfirmed',
country: 'RU',
media: []
}
}
JSON request for message in default locale
Request
http://www.ufoseti.org/api/v1/messages/7.json?locale=ru
Responce
{
message: {
id: 7,
observed_at: 2010-01-14T015:23:25Z,
place: 'Поселок Марямяги',
note: 'Второе сообщение 5',
comment: nil,
direction: 'Север',
shape: 'Треугольный',
investigation_status: 'Непроверено',
country: 'RU',
media: []
}
}
XML request for message in specific locale
Request
http://www.ufoseti.org/api/v1/messages/7.xml?locale=en
Responce
<?xml version="1.0" encoding="UTF-8"?>
<message>
<id type="integer">7</id>
<observed-at type="datetime">2010-01-14T015:23:25Z</observed-at>
<place>Marjamagi Village</place>
<note>Additional Info</note>
<comment>Moderator's comment</comment>
<direction>North</direction>
<shape>Triangle</shape>
<investigation_status>Unconfirmed</investigation_status>
<country>RU</country>
<media type="array"/>
</message>
JSON reuest for non-existed massage
Request
http://www.ufoseti.org/api/v1/messages/15.json?locale=en
Responce
{
error: {
description: 'Message not exist'
}
}
Multiple mesages
На ряду с получением деталей конкретного сообщения, имееться так же возможность получения нескольких сообщений за один запрос (сообщения выдаются в обратном хронологическом порядке):
http://www.ufoseti.org/api/v1/messages.(:format)?(locale=:lacale)&(countries=:country)&(limit=:limit)
where parameters are:
- format - an expected output format. Possible options: JSON, XML. Default is: JSON.
- locale - указание на язык в котором сообщения будут возвращены. Возможные варианты: указыватся по стандарту ISO 3166-1 alpha-2 (двух символьным кодом). Данный параметр являеться необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: en.
- countries - фильтрация сообщений по странам. Обозначения стран указыватся по стандарту ISO 3166-1 alpha-2(двух символьным кодом), коды должыны быть перечисленны через запятую, без пробелов. Данный параметр являеться необязательным и может быть опущен, в таком случае будут выданы все последние присланные сообщения.
- limit - лимитирование количества возвращаемых сообщений. Данный параметр являеться необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: 20.
JSON запрос возвращающих детали послених сообщений в стандартной локали
Request
http://www.ufoseti.org/api/v1/messages.json
Responce
{
messages: [
{
id: 2,
observed_at: "2010-01-14T015:23:25Z",
place: "Mars Village",
note: "Additional Info 1",
comment: "Moderator's comment",
direction: "North",
shape: "Triangle",
investigation_status: "Unconfirmed",
country: 'EE',
media: []
},
{
id: 1,
observed_at: "2010-01-11T023:17:41Z",
place: "Mars Village",
note: "Additional Info 2",
comment: "Moderator's comment",
direction: "North",
shape: "Triangle",
investigation_status: "Unconfirmed",
country: 'LV',
media: []
}
]
}
XML запрос возвращающих детали послених сообщений в стандартной локали
Request
http://www.ufoseti.org/api/v1/messages.xml
Responce
<?xml version="1.0" encoding="UTF-8"?>
<messages type="array">
<message>
<id type="integer">7</id>
<observed-at type="datetime">2010-01-14T015:23:25Z</observed-at>
<place>Mars Village</place>
<note>Additional Info</note>
<comment>Moderator's comment</comment>
<direction>North</direction>
<shape>Triangle</shape>
<investigation_status>Unconfirmed</investigation_status>
<country>LV</country>
<media type="array"/>
</message>
...
<message>
<id type="integer">1</id>
<observed-at type="datetime">2010-01-11T023:17:41Z</observed-at>
<place>Mars Village</place>
<note>Additional Info</note>
<comment>Moderator's comment</comment>
<direction>North</direction>
<shape>Triangle</shape>
<investigation_status>Unconfirmed</investigation_status>
<country>LV</country>
<media type="array"/>
</message>
</messages>
JSON запрос возвращающих детали послених сообщений в указаной локали
Request
http://www.ufoseti.org/api/v1/messages.json?locale=ru
Responce
{
messages: [
{
id: 7,
observed_at: "2010-01-14T015:23:25Z",
place: "Poselok Mars",
note: "Second message 2",
comment: nil,
direction: "Север",
shape: "Треугольный",
investigation_status: "Непроверено",
country: 'LV',
media: []
},
...
{
id: 1,
observed_at: "2010-01-11T023:17:41Z",
place: "Poselok Mars",
note: "Second message 1",
comment: nil,
direction: "Север",
shape: "Треугольный",
investigation_status: "Непроверено",
country: 'LV',
media: []
}
]
}
JSON запрос возвращающих детали послених сообщений ограницивающий их колличество
Request
http://www.ufoseti.org/api/v1/messages.json?locale=ru&limit=3
Responce
{
messages: [
{
id: 7,
observed_at: "2010-01-14T015:23:25Z",
place: "Поселок Марямяги",
note: "Второе сообщение 5",
comment: nil,
direction: "Север",
shape: "Треугольный",
investigation_status: "Непроверено",
country: 'RU',
media: []
},
{
id: 6,
observed_at: "2010-01-14T015:23:25Z",
place: "Поселок Марямяги",
note: "Второе сообщение 4",
comment: nil,
direction: "Север",
shape: "Треугольный",
investigation_status: "Непроверено",
country: 'RU',
media: []
},
{
id: 5,
observed_at: "2010-01-14T015:23:25Z",
place: "Поселок Марямяги",
note: "Второе сообщение 3",
comment: nil,
direction: "Север",
shape: "Треугольный",
investigation_status: "Непроверено",
country: 'RU',
media: []
}
]
}