Описание API системы UfoSeti

Зачем нужен API?

Application Programming Interface (API) в мире software - протокол обмена информацией и командами с различными приложением. Он используется для интеграции одного приложения с другим. Система UfoSeti предоставляет собственный API для всех желающих, без каких либо существенных ограничений, для самостоятельной интеграции со своими ресурсами.

Возможности API

Система UfoSeti предоставляет для заинтересованных сторон доступ к базе подтверждённых и расследованных сообщений, а так же возможность присылать сообщения посредством POST запроса. Выдача сообщений возможна в двух форматах: JSON и XML. Так же возможно получение общей статистики.

Получение общей информации

UfoSeti API предоставляет общую информацию о находящихся в базе сообщениях. Для получения текущего статуса базы клиентское приложение должно прислать запрос следующего вида:

format - формат, в котором будет выдана информация на присланный запрос. Возможные варианты: JSON, XML. Формат по умолчанию: JSON.
countries - фильтрация сообщений по странам. Обозначения стран указывается по стандарту ISO 3166-1 alpha-2 (двух символьным кодом), коды должны быть перечислены через запятую, без пробелов. Данный параметр является необязательным и может быть опущен, в таком случае будет выдана общая информация о состоянии базы.

JSON запрос, возвращающий информацию для всех стран

Запрос

http://www.ufoseti.org/api/v1/messages/status.json

Ответ

{
  statistics: {
    total_messages: 345,
    last_message_id: 372,
    last_message_posted_at: 2012-03-30T05:43:25Z
  }
}

XML запрос, возвращающий информацию для всех стран

Запрос

http://www.ufoseti.org/api/v1/messages/status.xml

Ответ

<?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 запрос, возвращающий информацию для конкретных стран

Запрос

http://www.ufoseti.org/api/v1/messages/status.json?countries=ru,ee,lv,lt

Ответ

{
  statistics: {
    total_messages: 115,
    last_message_id: 321,
    last_message_posted_at: 2011-11-25T05:43:25Z
  }
}

JSON запрос, отфильтровывающий все сообщения

Запрос

http://www.ufoseti.org/api/v1/messages/status.json?countries=za

Ответ

{
  statistics: {
    total_messages: 0
  }
}

Получение конкретного сообщения

Помимо получения общей статистики по базе данных, так же, имеется возможность получения информации, о конкретном сообщении. Для этого, клиентское приложение, должно прислать следующий запрос:

http://www.ufoseti.org/api/v1/messages/1.(:format)?(locale=:locale)

гдe параметры имеют следующее значение:

format - формат, в котором будет выдана информация на присланный запрос. Возможные варианты: JSON, XML. Формат по умолчанию: JSON.
locale - указание на язык возвращаемого сообщения. Возможные варианты: указываются по стандарту ISO 3166-1 alpha-2 (двух символьным кодом). Данный параметр является необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: en.

Примеры:

JSON запрос, возвращающий детали сообщения в переведенном виде

Запрос

http://www.ufoseti.org/api/v1/messages/7.json

Ответ

{
  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 запрос, возвращающий детали сообщения в переведенном виде

Запрос

http://www.ufoseti.org/api/v1/messages/7.json?locale=ru

Ответ

{
  message: {
    id: 7,
    observed_at: 2010-01-14T015:23:25Z,
    place: 'Поселок Марьямяги',
    note: 'Второе сообщение 5',
    comment: nil,
    direction: 'Север',
    shape: 'Треугольный',
    investigation_status: 'Не проверено',
    country: 'RU',
    media: []
  }
}

XML запрос, возвращающий детали сообщения в переведенном виде

Запрос

http://www.ufoseti.org/api/v1/messages/7.xml?locale=en

Ответ

<?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 запрос, возвращающий ответ о не существующем сообщении

Запрос

http://www.ufoseti.org/api/v1/messages/15.json?locale=en

Ответ

{
  error: {
    description: 'Message not exist'
  }
}

Получение множественных сообщений

На ряду с получением деталей конкретного сообщения, имеется также возможность получения данных сразу нескольких сообщений, за один запрос (сообщения выдаются в обратном хронологическом порядке):

http://www.ufoseti.org/api/v1/messages.(:format)?(locale=:lacale)&(countries=:country)&(limit=:limit)

гдe параметры имеют следующее значение:

format - формат, в котором будет выдана информация на присланный запрос. Возможные варианты: JSON, XML. Формат по умолчанию: JSON.
locale - указание на язык, на котором сообщения будут возвращены. Возможные варианты: указываются по стандарту ISO 3166-1 alpha-2 (двух символьным кодом). Данный параметр является необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: en.
countries - фильтрация сообщений по странам. Обозначения стран указываются по стандарту ISO 3166-1 alpha-2(двух символьным кодом), коды должны быть перечислены через запятую, без пробелов. Данный параметр является необязательным и может быть опущен, в таком случае будут выданы все последние присланные сообщения.
limit - лимитирование количества возвращаемых сообщений. Данный параметр является необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: 20.

JSON запрос, возвращающий детали последних сообщений в стандартной локали

Запрос

http://www.ufoseti.org/api/v1/messages.json

Ответ

{
  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 запрос, возвращающий детали последних сообщений в стандартной локали

Запрос

http://www.ufoseti.org/api/v1/messages.xml

Ответ

  <?xml version="1.0" encoding="UTF-8"?>
  <messages type="array">
    <message>
      <id type="integer">2</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 запрос, возвращающий детали последних сообщений в указанной локали

Запрос

http://www.ufoseti.org/api/v1/messages.json?locale=ru

Ответ

{
  messages: [
    {
      id: 2,
      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 запрос, возвращающий детали последних сообщений, ограничивающий их количество

Запрос

http://www.ufoseti.org/api/v1/messages.json?locale=ru&limit=3

Ответ

{
  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: []
    }
  ]
}