███████╗
██╔════╝
█████╗  
██╔══╝  
██║     
╚═╝     
actopedia

Разработчики

Хотим выразить большую благодарность таким проектам как PHP, Yii Framework, MySQL, Memcached, Sphinx Search благодаря им появилась Factopedia.

Если вы как и мы хотите сделать Factopedia лучше тогда присоединяйтесь к нам. Прямо сейчас вы можете помочь нам перевести Factopedia на ваш родной язык, или наполнить энциклопедию необходимым контентом. Для того что бы добавлять объекты в базу из вашего скрипта, используйте наше RESTful API, которое доступно по адресу https://api.factopedia.org. Если вы хотите участвовать в разработке Factopedia, пожалуйста свяжитесь с нами.

Содержание

  1. Авторизация
  2. Формат данных
  3. Конечные точки (endpoints)
    1. Общие принципы
    2. /objects
      1. GET /objects вывод перечня объектов
      2. POST /objects добавление нового объекта
      3. PUT /objects/123 редактирование объекта
    3. /properties
    4. /properties-categories
    5. /units
    6. /comparisons
      1. GET /comparisons вывод перечня сравнений.
      2. POST /comparisons добавление нового сравнения
  4. Реализация API на разных языках
    1. PHP

Авторизация

Только зарегистрированные пользователи могут использовать API поэтому зарегистрируйтесь или войдите. Авторизация пользователя происходит с помощью HTTP Basic Access Authentication в качестве имя пользователя используйте свой API token который найдёте у себя в профиле.Пароль оставьте пустым.
Что бы автоматически делать запросы на API добавьте в заголовки запроса заголовок Authorization с данными Basic {credentials} где {credentials} - закодированный в base64 {token}:, двоеточие на конце обязательно.

Формат данных

Если в запросе присутствует заголовок
Accept: application/json; q=1.0, */*; q=0.1
Данные будут возвращены в JSON формате, иначе в XML

Конечные точки (endpoints)

  1. /objects
  2. Получение информации по объектам, добавление, правка объектов
  3. /properties
  4. Получение информации по свойствам, добавление новый свойств
  5. /units
  6. Получение информации по единицам измерения, добавление новых единиц измерения
  7. /comparisons
  8. Сравнение объектов, добавление, правка сравнений

Общие принципы

Все запросы выборки GET можно расширять дополнительными параметрами

    expand: получить дополнительную информацию;
    filter: отфильтровать, сделать поиск *;
    sort: отсортировать объекты в определённом порядке *; 

* работает только на конечных точках которые возвращают перечень объектов

возможные значения параметра expand для каждой конечной точки будут свои, они будут указываться в описании к конечно точке.

filter в общем имеет следующий формат


filter[name]{[operator]}=value

{} operator необязательная часть

sort в общем имеет следующий формат


sort=name

name - это название поля. По умолчанию сортировка ASC, от меньшего к большему, если вы хотите отсортировать в обратном порядке используйте знак "-" перед полем,то есть sort=-name

/objects

Конечные точки (endpoints)

GET /objects: перечень всех объектов страница за страницей;
POST /objects: добавление нового объекта;
GET /objects/123: информация об объекте 123;
PATCH /objects/123 или PUT /objects/123: редактировать объект 123;

GET /objects перечень всех объектов страница за страницей

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

name
parentId
property
lang

Это позволяет искать объекты по имени, в определённых категориях и с определёнными значениями свойств. "property" используется только с "parentId" для поиска объектов в категориях. Это массив в котором ключи это "property_id" а значение многоуровненый массив с настройками фильтра (смотрите пример использования что бы понять как пользоваться этим параметром). По умолчанию объекты отсортированы по названию, но так же можно сортировать по свойствам объектов например "sort=-67_object" это значит что объекты будут отсортированы в обратной порядке "-" вначале, по свойству с порядковым номером 67 у которого тип "object" Возможные значения дополнительных параметров

expand


properties
suggestedProperties
parents
children
countChildren
images

Пример использования

GET /objects?expand=properties,suggestedProperties,parents,children&sort=-67_object&name=example&parentId=123&lang=ru&property[65][int][][>=]=1980&property[65][int][][<=]=1981&property[62][int][][%3D]=7&property[62][int][][%3D]=8

POST /objects добавление нового объекта

Вначале ознакомьтесь с соответствующим разделом помощи, который описывает добавление новых объектов. Данные могут отправляться в формате www-url-form-encode если вы не отправляете изображения, и в формате multipart/form-data если вы отправляете или не отправляете изображения

name: название объекта (*);
lang: языковая версия сайта в двухбуквенном формате (*);
descriptions: описание;
main_image: md5 checksum файла картинки;
aliases[]: другие названия объекта;
parents[][Objects][id]:  родительский объект (категория);
children[][Objects][id]:  объекты детей, объекты произошедшие от данного объекта;
objects[imageFiles][]: файлы фотографий;

objectsPropertiesValues[n][ObjectsPropertiesValues][name]: данные по каждому свойству, n - ID свойства, возможные значения поля name смотрите в выводе конечной точки /properties
    обязательные поля:
    objectsPropertiesValues[n][ObjectsPropertiesValues][property_id]: ID названия свойства, название свойства должно быть предварительно добавлено если такого названия ещё не присутствует в базе, проверить наличие или добавить можно на конечной точке /properties
    возможные значения поля type:
    int, dec, range_int, range_dec, bool, text, object, array, array_of_objects, dynamic
Links[n][url]: ссылка на свойство, n - ID свойства;


Например:
POST /objects

?name=foo
&lang=ru
&description=bar
&aliases[]=foobar
&aliases[]=barfoo
&parents[][Objects][id]=123
&children[][Objects][id]=234
&objectsPropertiesValues[12][ObjectsPropertiesValues][property_id]=12
&objectsPropertiesValues[12][ObjectsPropertiesValues][category_id]=11
&objectsPropertiesValues[12][ObjectsPropertiesValues][unit_id]=21
&objectsPropertiesValues[12][ObjectsPropertiesValues][type]=int
&objectsPropertiesValues[12][ObjectsPropertiesValues][value]=4321
&objectsPropertiesValues[12][ObjectsPropertiesValues][order_by]=1
&objectsPropertiesValues[13][ObjectsPropertiesValues][property_id]=13
&objectsPropertiesValues[12][ObjectsPropertiesValues][category_id]=11
&objectsPropertiesValues[13][ObjectsPropertiesValues][unit_id]=31
&objectsPropertiesValues[13][ObjectsPropertiesValues][type]=bool
&objectsPropertiesValues[13][ObjectsPropertiesValues][value]=1
&objectsPropertiesValues[13][ObjectsPropertiesValues][order_by]=2
&Links[12][url]=http://www.example.com
&Links[13][url]=http://www.example1.com

* Обязательные данные

GET /objects/123 получение данных по объекту

Смотрите описание команды GET /objects, данная команда принимает такие же параметры. Дополнительные параметры:

format: формат возвращаемых данных. Используется что бы сразу сгенерировать данные для команды редактирования объекта PUT /objects/123. Возможные значения: api

Пример использования

GET /objects/123
GET /objects/123?format=api

PUT /objects/123 редактирование объекта

Смотрите описание команды POST /objects, данная команда принимает такие же параметры. Внимание когда редактируете хотя бы одно поле, необходимо отправить и все остальные поля только в неизменном виде. Что бы получить POST данные для какого либо объекта, добавьте параметр format=api в запрос GET /object/123

/properties

Получение и добавление в базу данных названий свойств которые могут присутствовать у объектов. Ознакомьтесь с общими принципами команд возвращающих перечень.

Конечные точки (endpoints)


GET /properties: перечень всех свойств страница за страницей;
POST /properties: добавление нового свойства;
GET /properties/123: информация о свойстве 123;

Примеры использования:

GET /properties?filter[name]=foo&lang=ru
GET /properties?filter[name][like]=bar&lang=ru&sort=name
POST /properties&name=foo&lang=ru

/properties-categories

Получение и добавление в базу данных названий категорий свойств которые могут присутствовать у объектов. Ознакомьтесь с общими принципами команд возвращающих перечень.

Конечные точки (endpoints)


GET /properties-categories: перечень всех категорий свойств страница за страницей;
POST /properties-categories: добавление новой категории;
GET /properties-categories/123: информация о категории  номер 123;

Примеры использования:

GET /properties-categories?filter[name]=foo&lang=ru
GET /properties-categories?filter[name][like]=bar&lang=ru&sort=name
POST /properties-categories&name=foo&lang=ru

/units

Получение и добавление в базу данных названий единиц изменения которые могут присутствовать у свойств объекта. Ознакомьтесь с общими принципами команд возвращающих перечень.

Конечные точки (endpoints)


GET /units: перечень всех единиц измерения страница за страницей;
POST /units: добавление новой единицы измерения;
GET /units/123: информация о единице измерения 123;

Примеры использования:

GET /units?filter[name]=foo&lang=ru
GET /units?filter[name][like]=bar&lang=ru&sort=-name
POST /units&name=foo&lang=ru

/comparisons

Конечные точки (endpoints)

GET /comparisons: перечень всех сравнений страница за страницей;
POST /comparisons: добавление нового сравнения;
GET /comparisons/123: информация о сравнении 123;
PATCH /comparisons/123 или PUT /comparisons/123: редактировать сравнение 123;

GET /comparisons перечень всех сравнений страница за страницей

Ознакомьтесь с общими принципами команд возвращающих перечень. Возможные значения дополнительных параметров

expand


sortings
sortings.property
objects

Пример использования

GET /comparisons?expand=sortings.property,objects&filter[name][like]=Foobar&filter[lang]=ru&sort=-id

POST /comparisons добавление нового сравнения

Вначале ознакомьтесь с соответствующим разделом помощи, который описывает сравнение объектов. Данные могут отправляться в формате www-url-form-encode

name: название сравнения;
lang: языковая версия сайта в двухбуквенном формате (*);
descriptions: описание;

comparisonsSortings[n][ComparisonsSortings][name]: данные по каждому свойству, n - ID свойства, возможные значения поля name:
    comparisonsSortings[n][ComparisonsSortings][property_id] *: ID свойства
    comparisonsSortings[n][ComparisonsSortings][order] *: номер сортировки (1-10)
    comparisonsSortings[n][ComparisonsSortings][direction]: направление сортировки (asc, desc)


Например:
POST /comparisons

?objects[][Objects][id]=123
&objects[][Objects][id]=456
&name=Foo bar
&lang=ru
&comparisonsSortings[34][ComparisonsSortings][property_id]=34
&comparisonsSortings[34][ComparisonsSortings][order]=1
&comparisonsSortings[34][ComparisonsSortings][direction]=asc
&comparisonsSortings[35][ComparisonsSortings][property_id]=35
&comparisonsSortings[35][ComparisonsSortings][order]=1
&comparisonsSortings[35][ComparisonsSortings][direction]=desc

* Обязательные данные

English · Помощь · Обратная связь · Отказ от ответственности · Авторы · Разработчики · Пожертвовать