Документация API

1. Общая информация

  • API работает по протоколу HTTPS;
  • Авторизация осуществляется по протоколу OAuth2;
  • Все данные доступны только в формате JSON;
  • Базовый URL — https://api.moikrug.ru/

2. Начало работы

Для использования API вам необходимо зарегистрировать приложение по адресу https://moikrug.ru/profile/applications и настроить процесс авторизации.

Авторизация осуществляется по протоколу OAuth 2.0. Подробная документация по протоколу: RFC 6749.

Зарегистрированное приложение может запрашивать у пользователей moikrug.ru разрешение доступа к их персональным данным, без получения и хранения их логина и пароля.

После создания приложения вам необходимо написать нам письмо на адрес hr@tmtm.ru с просьбой активировать ваше приложение. В письме обязательно укажите название вашего приложения и Client ID.

3. Процесс авторизации

В начале необходимо направить пользователя на страницу по адресу:

https://moikrug.ru/integrations/oauth/authorize?
client_id={client_id}&
redirect_uri={redirect_uri}&
response_type=code

Обязательные параметры:

  • response_type=code — указание на способ получения авторизации;
  • client_id — идентификатор, полученный при создании приложения;
  • redirect_uri — uri для перенаправления пользователя после авторизации. Значение параметра валидируется, вам может потребоваться сделать urlencode значения данного параметра.

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

Если пользователь не разрешает доступ приложению, то он будет перенаправлен на указанный redirect_uri с параметром error=access_denied.

В случае разрешения прав, в редиректе будет указан временный authorization_code.

Если пользователь авторизован на сайте и доступ данному приложению уже был выдан ранее, то ответом сразу будет вышеописанный редирект с authorization_code.

После получения authorization_code приложению необходимо осуществить POST-запрос на адрес https://moikrug.ru/integrations/oauth/token для обмена полученного authorization_code на access_token.

https://moikrug.ru/integrations/oauth/token?
client_id={client_id}&
client_secret={client_secret}&
redirect_uri={redirect_uri}&
grant_type=authorization_code&
code={authorization_code}

Обязательные параметры:

  • grant_type=authorization_code
  • client_id, client_secret, redirect_uri - значения, полученные при регистрации приложения
  • code - значение authorization_code, полученное при перенаправлении пользователя

В ответ сервер пришлет JSON следующего вида:

{
"access_token": "ede87aba4312e7ff423e46745d6b17f04ff1a785603360b23e79b6b00f98a3af",
"token_type": "bearer",
"scope": "public",
"created_at": 1502376342
}

Если обмен authorization_code произвести не удалось, то сервер вернётся ответ со статусом 400 Bad Request и следующим содержанием:

{
"error": "invalid_request",
"error_description": "bad redirect url"
}

4. Сроки жизни токенов

Время жизни authorization_code - 10 минут, access_token в текущей реализации перманентен.

5. Использование access-токена

Полученный access_token необходимо передавать в качестве параметра при любом запросе к API, например:

https://api.moikrug.ru/v1/integrations/vacancies?
access_token=ede87aba4312e7ff423e46745d6b17f04ff1a7856

6. Методы API

GET /v1/integrations/users/me

Ответ:

Успешный ответ приходит с кодом 200 OK и содержит информацию о текущем пользователе:

{
"login": "ivanov",
"email": "ivanov@domain.com",
"first_name": "Иван",
"last_name": "Иванов",
"middle_name": "Иванович",
"birthday": "1990-08-15",
"avatar": "https://hsto.org/getpro/moikrug/uploads/company/348/850/484/logo/medium_cd41dce48c924bbcd134b5a8aac27be1.png",
"location": {
    "city": "Москва",
    "country": "Россия"
},
"gender": "male"
}

Описание полей:

Название поляТипОписание
loginstringЛогин пользователя
emailstringEmail пользователя
first_namestringИмя
last_namestringФамилия
middle_namestringОтчество
birthdaystringДень рождения
avatarstringСсылка на аватар пользователя
location/citystringГород
location/countrystringСтрана
genderstringПол

GET /v1/integrations/vacancies

Опциональные параметры:

page - номер страницы

Ответ:

Успешный ответ приходит с кодом 200 OK и содержит массив вакансий:

{
  "vacancies": [
    {
        "id": 19,
        "title": "Вакансия 1",
        "published_at": "2017-07-25T18:46:24.159+03:00",
        "url": "https://moikrug.ru/vacancies/19",
        "location": "Россия, Москва",
        "city": "Москва",
        "marked": false,
        "company": {
            "name": "Компания 1",
            "alias_name": "company1",
            "url": "https://moikrug.ru/companies/company1",
            "logo_url": "https://hsto.org/getpro/moikrug/uploads/company/348/850/484/logo/medium_cd41dce48c924bbcd134b5a8aac27be1.png"
        },
        "employment_type": "Полный рабочий день",
        "salary": "от 50 000 до 60 000 руб."
    },
    {
        "id": 16,
        "title": "Вакансия 2",
        "published_at": "2017-07-31T00:00:45.321+03:00",
        "url": "https://moikrug.ru/vacancies/16",
        "location": "Россия, Москва",
        "city": "Москва",
        "marked": false,
        "company": {
            "name": "Компания 2",
            "alias_name": "company2",
            "url": "https://moikrug.ru/companies/company2",
            "logo_url": "https://hsto.org/getpro/moikrug/uploads/company/348/850/484/logo/medium_cd41dce48c924bbcd134b5a8aac27be1.png"
        },
        "employment_type": "Полный рабочий день",
        "salary": "от 90 000 до 100 000 руб."
    }
  ],
  "pagination": {
      "total": 2,
      "page": 0,
      "per": 20
  }
}

Описание полей вакансии:

Название поляТипОписание
idnumberID вакансии
titlestringЗаголовок вакансии
published_atstringДата публикации
urlstringСсылка на вакансию
locationstringРегион размещения вакансии
citystringГород размещения вакансии
markedbooleanПризнак того, что вакансия выделена
company/namestringНазвание компании
company/alias_namestringАлиас компании
company/urlstringСсылка на компанию
company/logo_urlstringСсылка на логотип компании
employment_typestringТип трудоустройства
salarystringВилка зарплат

GET /v1/integrations/vacancies/{vacancy_id}/responses

Обязательные параметры:

vacancy_id - идентификатор вакансии

Опциональные параметры:

page - номер страницы

Ответ:

Успешный ответ приходит с кодом 200 OK и содержит массив откликов на вакансию:

{
  "responses": [
      {
          "vacancy_id": 19,
          "user": "someuser",
          "body": "Отклик",
          "favorite": false,
          "created_at": "2017-08-11T00:17:47.827+03:00"
      }
  ],
  "pagination": {
      "total": 1,
      "page": 0,
      "per": 20
  }
}

Описание полей отклика:

Название поляТипОписание
vacancy_idnumberID вакансии
userstringЛогин пользователя, оставившего отклик
bodystringСопроводительное письмо
favoritebooleanПризнак того, что отклик отмечен пользователем, разместившим вакансию
created_atstringДата размещения отклика на вакансию

GET /v1/integrations/users/{login}

Обязательные параметры:

login - логин пользователя

Ответ:

Успешный ответ приходит с кодом 200 OK и содержит полную информацию о пользователе:

{
  "login": "ivanov",
  "full_name": "Иван Иванов",
  "location": {
      "city": "Москва",
      "country": "Россия"
  },
  "relocation": true,
  "remote": false,
  "experience_total": 55,
  "age": 33,
  "salary": {
      "from": 50000,
      "currency": "rur"
  },
  "resume_headline": "Дизайнер",
  "contacts": {
      "emails": [
          {
              "type": "email",
              "value": "email@email.ru"
          }
      ],
      "phones": [
          {
              "type": "phone_work",
              "value": "+7 111-11-11"
          }
      ],
      "messengers": [
          {
              "type": "skype",
              "value": "ivan.ivanov"
          },
          {
              "type": "icq",
              "value": "4322435"
          },
          {
              "type": "telegram",
              "value": "someuser"
          }
      ],
      "sites": [
          {
              "type": "site",
              "value": "https://moikrug.ru"
          }
      ]
  },
  "avatar": "https://hsto.org/getpro/moikrug/uploads/company/348/850/484/logo/medium_cd41dce48c924bbcd134b5a8aac27be1.png",
  "skills": [
      {
          "title": "Разработка",
          "alias_name": "coding"
      },
      {
          "title": "Дизайн",
          "alias_name": "design"
      }
  ],
  "birthday": "1987-08-11",
  "about": "<p>О себе</p>",
  "url": 'https://moikrug.ru',
  "experiences": [
      {
          "start_date": "2013-05-01",
          "end_date": "2014-05-01",
          "company_name": "Компания",
          "position": "Дизайнер",
          "location": {
              "city": "Москва",
              "country": "Россия"
          },
          "description": "Должностные обязанности"
      }
  ],
  "university_educations": [
      {
          "start_date": "2013-05-01",
          "end_date": "2014-05-01",
          "university_name": "Университет",
          "faculty_name": "Факультет",
          "location": {
              "city": "Москва",
              "country": "Россия"
          },
          "description": "Учебная специализация и достижения"
      }
  ],
  "college_educations": [
      {
          "start_date": "2013-05-01",
          "end_date": "2014-05-01",
          "college_name": "СУЗ",
          "faculty": "Факультет",
          "location": {
              "city": "Москва",
              "country": "Россия"
          },
          "description": "Учебная специализация и достижения"
      }
  ],
  "opinions": [
    {
      "creator" : {
        "name": "otheruser",
        "resume_headline": "Специализация",
        "working_relationship": "руководитель"
      },
      "body": "Отзыв",
      "created_at": "2017-08-11T00:17:47.827+03:00"
    }
  ],
  "social_ratings": [
      {
          "kind": "github",
          "registered_at": "2010-02-25T02:21:44.000+03:00",
          "login": "somelogin",
          "stats": {
              "repos_count": 18,
              "contributions_count": 3194
          },
          "tags": [
              "Ruby",
              "Java",
              "ApacheConf",
              "JavaScript",
              "Go",
              "Erlang",
              "Shell",
              "Vim script"
          ]
      }
  ]
}

Описание полей:

Название поляТипОписание
loginstringЛогин пользователя
full_namestringПолное имя пользователя
location/citystringГород пользователя
location/countrystringСтрана пользователя
relocationbooleanПоказатель того, что пользователь готов к релокации
remotebooleanПоказатель того, что пользователь готов к удаленной работе
experience_totalnumberОбщий стаж пользователя (в месяцах)
agenumberВозраст пользователя (полных лет)
salary/fromnumberОжидаемое вознаграждение
salary/currencystringВалюта
resume_headlinestringСпециализация
contacts/emails/type
contacts/phones/type
contacts/messengers/type
contacts/sites/type
stringТип контакта
contacts/emails/value
contacts/phones/value
contacts/messengers/value
contacts/sites/value
stringКонтакт пользователя
avatarstringСсылка на аватар пользователя
skills/titlestringНазвание навыка пользователя
skills/alias_namestringАлиас навыка
birthdaystringДень рождения пользователя
aboutstringО себе
urlstringСсылка на сайт пользователя
experiences
start_datestringДата начала работы в компании
end_datestringДата окончания работы в компании (Значение этого параметра равное null означает, что пользователь работает в компании по настоящее время)
company_namestringНазвание компании
positionstringДолжность
location/citystringГород
location/countrystringСтрана
descriptionstringДолжностные обязанности и достижения
university_educations
start_datestringДата начала обучения в высшем учебном заведении
end_datestringДата окончания высшего учебного заведения
university_namestringНазвание высшего учебного заведения
faculty_namestringФакультет
location/citystringГород
location/countrystringСтрана
descriptionstringУчебные обязанности и достижения
college_educations
start_datestringДата начала обучения в среднем учебном заведении
end_datestringДата окончания среднего учебного заведения
college_namestringНазвание среднего учебного заведения
faculty_namestringФакультет
location/citystringГород
location/countrystringСтрана
descriptionstringУчебные обязанности и достижения
opinions
creator/namestringЛогин пользователя, оставившего отзыв
creator/resume_headlinestringСпециализация пользователя, оставившего отзыв
creator/working_relationshipstringУровень отношений с пользователем, оставившим отзыв
bodystringСодержание отзыва
created_atstringДата создания отзыва
social_ratings
kindstringТип социальной сети
registered_atstringДата регистрации в социальной сети
loginstringЛогин в социальной сети
stats/repos_countstringКоличество репозиториев (только для Github)
stats/contributions_countstringКоличество вкладов (только для Github)
stats/publications_countstringКоличество публикаций (для Хабрахабра и Гиктаймс)
stats/comments_countstringКоличество комментариев (для Хабрахабра и Гиктаймс)
stats/questions_countstringКоличество вопросов (для Тостера и Stackoverflow)
stats/answers_countstringКоличество ответов (для Тостера и Stackoverflow)
tagsstringСписок тегов, с которыми связан пользователь