Разное

Posting php разместить вакансию заголовок: Пример post запроса с отправкой заголовков? — Хабр Q&A

15.10.2021

Содержание

HTTP API: основы построения

Рекомендации по проектированию HTTP API, которые почерпнуты из API облачной платформы Heroku. Здесь вы также найдёте информацию о функционале и внутреннем API в Heroku.

Основными целями при построении HTTP API является соблюдение последовательности и концентрация на реализации бизнес-логики. Мы ищем различные, не обязательно самые лучшие, но хорошо документируемые способы разработки API.

  1. Основы
  2. Запросы
  3. Построение пути к ресурсу
  4. Ответы
  5. Артефакты
  6. Выводы

Основы

Принцип разделения ответственности

При проектировании старайтесь сохранять простоту системы, разделяя ответственность между различными частями цикла «запрос-ответ».  При этом простота принимаемых решений позволит концентироваться на решении все более сложных задач. Запросы и ответы выполняются для получения доступа к определенному ресурсу или набору ресурсов. Для определения сущности, которую необходимо получить, используйте путь и тело ответа для передачи содержимого, а заголовки — для передачи метаданных. Можно передавать все параметры в теле запроса, но, как показывает практика, такое решение является менее гибким. Более правильным подходом будет передача части параметров в заголовках.

Требуйте использования защищенных соединений

Для получения данных с помощью HTTP API используйте только защищенные соединения с TLS. Лучше решением было бы отклонять все запросы, не использующие TLS, а именно запросы по http или на 80-ый порт, во избежание небезопасного обмена данными. В случаях, когда это невозможно, отдавайте ответ 403 Forbidden.

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

Требуйте наличие версии в заголовке Accept

Наличие нескольких версий и переходы между ними может быть одним из самых сложных аспектов проектирования и использования API. Поэтому лучше заранее учесть этот момент.

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

Лучше всего – добавить версию в заголовок вместе с другими метаданными, используя заголовок Accept с пользовательским типом содержимого:

Accept: application/vnd.heroku+json; version=3

Используйте заголовок ETags для кеширования

Включайте заголовок ETags во все запросы, определяя при этом версию возвращаемого ресурса. Это позволит пользователям кэшировать ресурсы и реализовывать условные запросы при помощи использования заголовка If-None-Match, который поможет определить, нужно обновлять кэш или нет.

Используйте Request-ID для интроспекции

Включайте заголовок Request-Id, содержащий в себе UUID значение, в каждый ответ сервера. Регистрируя эти значения на клиенте, сервере или другом сервисе, вы получаете возможность отлаживать и диагностировать проблемы, связанные с запросами.

Разделяйте большие ответы сервера на несколько небольших при помощи заголовка Range

Большие ответы необходимо разбивать на более мелкие, используя заголовок Range. Для получения более детальной информации о заголовках запросов/ответов, кодах состояний и ограничениях изучите использование заголовка Range в API Heroku.

Запросы

Возвращайте соответствующие  коды состояний

Возвращайте соотвествующий код состояния HTTP в каждом ответе. Успешные ответы должны содержать такие коды состояний:

  • 200 – GET запрос завершился успешно, синхронный DELETE или PATCH запрос завершился успешно или синхронный PUT запрос обновил существующий ресурс.
  • 201 – Синхронный POST запрос завершился, синхронный PUT запрос создал новый ресурс.
  • 202 – Принят POST, PUT, DELETE или PATCH запрос, который будет обработан асинхронно.
  • 206 – GET запрос завершился успешно, но будет возвращен частичный ответ (см. раздел про заголовок Range).

Обратите внимание на использование кодов состояния ошибок авторизации и аутентификации:

  • 401 Unauthorized – запрос завершился с ошибкой, поскольку пользователь не прошел аутентификацию.
  • 403 Forbidden – запрос завершился с ошибкой, так как пользователь не авторизовался для получения доступа к определенному ресурсу.

Возвращайте соответствующие коды ошибок для предоставления дополнительной информации об их причинах:

  • 422 Unprocessable Entity – Ваш запрос был распознан, но содержит неверные параметры.
  • 429 Too Many Requests – Превышен лимит запросов, попробуйте позже.
  • 500 Internal Server Error – Проблема на стороне сервера, проверьте состояние сайта и/или сообщите о проблеме.

Для получения более подробной информации о кодах состояния HTTP изучите спецификацию.

По возможности, предоставляйте полные версии ресурсов

Возвращайте пользователям вашего API полное представление ресурса (то есть объект со всеми атрибутами) во всех ответах, где это возможно. Всегда предоставляйте полную версию ресурса в ответах на запросы с кодами состояния 200 и 201, включая PUT, PATCH и DELETE запросы.

$ curl -X DELETE \  
  

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
...
{
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

Ответы на запросы с кодом состояния 202 не должны содержать все поля объекта

$ curl -X DELETE \  
  

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
. ..
{}

API должен принимать сериализованный JSON в теле запроса

И предусматривать возможность передачи сереализованного JSON в теле PUT/PATCH/POST запросов вместо, либо в дополнение к передаваемым данным формы. Таким образом создается симметрия в JSON-ответах:

$ curl -X POST https://service.com/apps \
    -H "Content-Type: application/json" \
    -d '{"name": "demoapp"}'

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "demoapp",
  "owner": {
    "email": "[email protected]",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  ...
}

Построение пути к ресурсу

Названия ресурсов

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

Действия

Старайтесь проектировать такие конечные url, которые не требуют дополнительных действий для отдельных ресурсов. В случаях, когда это необходимо, добавляйте в общий путь компонент «action» для того, чтобы четко определить эти действия:

/resources/:resource/actions/:action

Например:

/runs/{run_id}/actions/stop

Используйте названия компонентов пути и атрибутов в нижнем регистре

Для названий компонентов пути к ресурсу используйте нижний регистр и разделяйте их при помощи дефиса.

service-api.com/users
service-api.com/app-setups

Названия атрибутов лучше писать в нижнем регистре, а в качестве разделителя лучше использовать нижнее подчеркивание – таким образом названия полей можно писать без скобок в Javascript:

service_class: "first"

API должен поддерживать доступ к ресурсу не только по его ID

В некоторых случаях для конечных пользователей неудобен доступ к ресурсу по его идентификатору. Например, пользователю удобнее для доступа к конкретному приложению Heroku использовать название приложения, а не его UUID. В таких случаях нужно организовать доступ как по имени, так и по идентификатору:

$ curl https://service. com/apps/{app_id_or_name}
$ curl https://service.com/apps/97addcf0-c182
$ curl https://service.com/apps/www-prod

Сведите к минимуму  количество вложений в пути для доступа к ресурсу

В моделях данных, в которых присутствуют родительские отношения между сущностями, пути доступа к ресурсам могут иметь большой уровень вложенности:

/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}

Вы можете ограничить глубину вложенности, если будете размещать ресурсы в корневой директории. Вложенность лучше использовать для обозначения доступа к коллекциям ресурсов:

/orgs/{org_id}
/orgs/{org_id}/apps
/apps/{app_id}
/apps/{app_id}/dynos
/dynos/{dyno_id}

Ответы

Предоставляйте UUID запрашиваемых ресурсов

У каждого ресурса по умолчанию должен быть атрибут id. В качестве значений идентификатора ресурса старайтесь всегда использовать UUID. Не используйте идентификаторы, которые не будут уникальными в масштабе вашего сервиса, особенно автоинкрементные идентификаторы.
UUID ресурса выводите в формате 8-4-4-4-12:

"id": "01234567-89ab-cdef-0123-456789abcdef"

Предоставляйте информацию о дате создания и изменения ресурса

По умолчанию ресурс должен хранить информацию о дате его создания created_at и обновления updated_at.

{
  // ...
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T13:00:00Z",
  // ...
}

Временные величины должны быть форматированы согласно ISO8601

Принимайте и возвращайте временные данные только в UTC, а выводите в формате ISO8601:

"finished_at": "2012-01-01T12:00:00Z"

Отношения с внешними сущностями должны быть вынесены во вложенный объект

Внешние отношения должны быть сериализованы как вложенный объект:

  "name": "service-production",
  "owner": {
    "id": "5d8201b0..."
  },
  // ...

А не как поле объекта:

{
  "name": "service-production",
  "owner_id": "5d8201b0. ..",
  // ...
}

Такой подход позволяет добавить больше информации о связанном объекте без необходимости менять структуру ответа:

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0...",
    "name": "Alice",
    "email": "[email protected]"
  },
  // ...
}

Создавайте структурированные ответы в случае возникновения ошибок

Отдавайте последовательное, структурированное тело ответа в случае возникновения ошибок. Ответ при этом должен содержать удобочитаемое сообщение об ошибке и, опционально,

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

HTTP/1.1 429 Too Many Requests
{
  "id":      "rate_limit",
  "message": "Account reached its API rate limit.",
  "url":     "https://docs.service.com/rate-limits"
}

Показывайте ограничение по количеству запросов

Ограничение по количеству запросов вводится для поддержания работоспособности системы и возможности качественного обслуживания других клиентов. Для расчета ограничений на количество запросов можно использовать алгоритм текущего ведра. Возвращайте оставшееся количество запросов для каждого запроса в заголовке ответа RateLimit-Remaining.

JSON во всех ответах должен быть минимизирован

Лишний пробел увеличивает размер ответа и многие Javascript клиенты для удобочитаемости автоматически отформатируют JSON. Поэтому лучше минимизировать JSON ответы:

{
 "beta":false,
 "email":"[email protected]",
 "id":"01234567-89ab-cdef-0123-456789abcdef",
 "last_login":"2012-01-01T12:00:00Z",
 "created_at":"2012-01-01T12:00:00Z",
 "updated_at":"2012-01-01T12:00:00Z"
}

вместо

{
  "beta": false,
  "email": "[email protected]",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z"
}

Вы можете опционально добавить возможность получать более развернутый ответ, указывая дополнительный параметр (например, ?pretty=true) или задавая значения для заголовка Accept (Accept: application/vnd.

heroku+json; version=3; indent=4;).

Артефакты

Предоставляйте удобную для обработки JSON-схему

Для точного описания вашего API предоставляйте JSON-схему. Для управления схемой используйте prmd, также удостоверьтесь в том, что она проходит валидацию при помощи команды prmd verify.

Предоставляйте удобочитаемую документацию

Если вы создали JSON-схему, используя prmd, как описано выше, вы можете легко сгенерировать Markdown документацию для всех конечных url, используя команду prmd doc.

Вдобавок к описанию конечных url, предоставьте обзор API, включая туда следующую информацию:

  • процесс аутентификации — получение и использование пользовательского токена;
  • стабильность API и его версию, а также информацию о том, как выбрать нужную версию API;
  • общие заголовки запросов и ответов;
  • формат выдачи ошибки;
  • примеры использования API с клиентами на разных языках;

Предоставляйте примеры запросов, которые можно протестировать

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

$ export TOKEN=... # acquire from dashboard
$ curl -is https://[email protected]/users

Если вы используете prmd для создания документации, то такие примеры будут сгенерированы автоматически для каждого конечного url.

Опишите стабильность вашего API

Вы можете описать степень стабильности API или отдельных конечных url при помощи установки флагов prototype/development/production.

Для получения дополнительной информации, вы можете изучить документ Политика совместимости Heroku API.

Как только вы объявили API готовым к релизу и стабильным, не стоит совершать модификаций, которые нарушают обратную совместимость внутри этой версии. Для внесения таких изменений создайте новою ветвь API с новым индексом версии.

Выводы

Разобрались, что HTTP API позволяет получить программный доступ к функциям некоторых веб-приложений, затронули запросы, ответы и артефакты. Для полного погружения держите советы по разработке REST API.

Перевод статьи «HTTP API Design Guide»

Контакты

В данном разделе описываются доступные методы для работы с сущностью контакта

Оглавление

  • Список контактов

  • Получение контакта по ID

  • Добавление контактов

  • Редактирование контактов

  • Привязка чатов к контактам

  • Получение списка чатов контакта

Список контактов

Метод

GET /api/v4/contacts

Описание

Метод позволяет получить список контактов в аккаунте.

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

ПараметрТип данныхОписание
withstringДанный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.
pageintСтраница выборки
limitintКоличество возвращаемых сущностей за один запрос (Максимум – 250)
querystring
int		Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
filterobjectФильтр. Подробней про фильтры читайте в отдельной статье
orderobjectСортировка результатов списка.
Доступные поля для сортировки: updated_at, id.
Доступные значения для сортировки: asc, desc.
Пример: /api/v4/contacts?order[updated_at]=asc
Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответаУсловие
200Запрос выполнен успешно
401Пользователь не авторизован
Параметры ответа

Метод возвращает коллекцию моделей контактов, рассмотрим ниже свойства контакта.

ПараметрТип данныхОписание
idintID контакта
namestringНазвание контакта
first_namestringИмя контакта
last_namestringФамилия контакта
responsible_user_idintID пользователя, ответственного за контакт
group_idintID группы, в которой состоит ответственны пользователь за контакт
created_byintID пользователя, создавший контакт
updated_byintID пользователя, изменивший контакт
created_atintДата создания контакта, передается в Unix Timestamp
updated_atintДата изменения контакта, передается в Unix Timestamp
is_deletedboolУдален ли элемент
closest_task_atintДата ближайшей задачи к выполнению, передается в Unix Timestamp
custom_fields_valuesarray
null		Массив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта
account_idintID аккаунта, в котором находится контакт
_embeddedobjectДанные вложенных сущностей
_embedded[tags]arrayДанные тегов, привязанных к контакту
_embedded[tags][0]objectМодель тега, привязанного к контакту
_embedded[tags][0][id]intID тега
_embedded[tags][0][name]stringНазвание тега
_embedded[tags][0][color]nullЦвет тега, доступен только для сделок
_embedded[companies]arrayДанные компании, привязанной к контакту. В массиве всегда 1 объект
_embedded[companies][0]objectДанные компании
_embedded[companies][0][id]intID компании, привязанной к контакту
_embedded[customers]arrayТребуется GET параметр with. Данные покупателей, привязанных к контакту
_embedded[customers][0]objectДанные покупателя
_embedded[customers][0][id]intID покупателя
_embedded[leads]arrayТребуется GET параметр with. Данные сделок, привязанных к контакту
_embedded[leads][0]objectДанные сделки
_embedded[leads][0][id]intID сделки
_embedded[catalog_elements]arrayТребуется GET параметр with. Данные элементов списков, привязанных к контакту
_embedded[catalog_elements][0]objectДанные элемента списка, привязанного к контакту
_embedded[catalog_elements][0][id]intID элемента, привязанного к контакту
_embedded[catalog_elements][0][metadata]objectМета-данные элемента
_embedded[catalog_elements][0][quantity]int
float		Количество элементов у контакта
_embedded[catalog_elements][0][catalog_id]intID списка, в котором находится элемент
_embedded[catalog_elements][0][price_id]intID поля типа Цена, которое установлено для привязанного элемента в сущности
Пример ответа
{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example. amocrm.ru/api/v4/contacts?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/contacts?limit=2&page=2"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 7143599,
                "name": "1",
                "first_name": "",
                "last_name": "",
                "responsible_user_id": 504141,
                "group_id": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1585758065,
                "updated_at": 1585758065,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/7143599"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            },
            {
                "id": 7767065,
                "name": "dsgdsg",
                "first_name": "",
                "last_name": "",
                "responsible_user_id": 504141,
                "group_id": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1586359590,
                "updated_at": 1586359590,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example. amocrm.ru/api/v4/contacts/7767065"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}
Параметры для GET-параметры with

ПараметрОписание
catalog_elementsДобавляет в ответ связанные с контактами элементы списков
leadsДобавляет в ответ связанные с контактами сделки
customersДобавляет в ответ связанных с контактами покупателей

Получение контакта по ID

Метод

GET /api/v4/contacts/{id}

Описание

Метод позволяет получить данные конкретного контакта по ID.

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

ПараметрТип данныхОписание
withstringДанный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.
Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответаУсловие
200Запрос выполнен успешно
204Контакт с указанным ID не существует
401Пользователь не авторизован
Параметры ответа

Метод возвращает модель контакта, рассмотрим ниже её свойства.

ПараметрТип данныхОписание
idintID контакта
namestringНазвание контакта
first_namestringИмя контакта
last_namestringФамилия контакта
responsible_user_idintID пользователя, ответственного за контакт
group_idintID группы, в которой состоит ответственны пользователь за контакт
created_byintID пользователя, создавший контакт
updated_byintID пользователя, изменивший контакт
created_atintДата создания контакта, передается в Unix Timestamp
updated_atintДата изменения контакта, передается в Unix Timestamp
is_deletedboolУдален ли элемент
closest_task_atintДата ближайшей задачи к выполнению, передается в Unix Timestamp
custom_fields_valuesarray
null		Массив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта
account_idintID аккаунта, в котором находится контакт
_embeddedobjectДанные вложенных сущностей
_embedded[tags]arrayДанные тегов, привязанных к контакту
_embedded[tags][0]objectМодель тега, привязанного к контакту
_embedded[tags][0][id]intID тега
_embedded[tags][0][name]stringНазвание тега
_embedded[tags][0][color]nullЦвет тега, доступен только для сделок
_embedded[companies]arrayДанные компании, привязанной к контакту. В массиве всегда 1 объект
_embedded[companies][0]objectДанные компании
_embedded[companies][0][id]intID компании, привязанной к контакту
_embedded[customers]arrayТребуется GET параметр with. Данные покупателей, привязанных к контакту
_embedded[customers][0]objectДанные покупателя
_embedded[customers][0][id]intID покупателя
_embedded[leads]arrayТребуется GET параметр with. Данные сделок, привязанных к контакту
_embedded[leads][0]objectДанные сделки
_embedded[leads][0][id]intID сделки
_embedded[catalog_elements]arrayТребуется GET параметр with. Данные элементов списков, привязанных к контакту
_embedded[catalog_elements][0]objectДанные элемента списка, привязанного к контакту
_embedded[catalog_elements][0][id]intID элемента, привязанного к контакту
_embedded[catalog_elements][0][metadata]objectМета-данные элемента
_embedded[catalog_elements][0][quantity]int
float		Количество элементов у контакта
_embedded[catalog_elements][0][catalog_id]intID списка, в котором находится элемент
_embedded[catalog_elements][0][price_id]intID поля типа Цена, которое установлено для привязанного элемента в сущности
Пример ответа
{
    "id": 3,
    "name": "Иван Иванов",
    "first_name": "Иван",
    "last_name": "Иванов",
    "responsible_user_id": 504141,
    "group_id": 0,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1582117331,
    "updated_at": 1590943929,
    "closest_task_at": null,
    "custom_fields_values": [
        {
            "field_id": 3,
            "field_name": "Телефон",
            "field_code": "PHONE",
            "field_type": "multitext",
            "values": [
                {
                    "value": "+79123",
                    "enum_id": 1,
                    "enum": "WORK"
                }
            ]
        }
    ],
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example. amocrm.ru/api/v4/contacts/3"
        }
    },
    "_embedded": {
        "tags": [],
        "leads": [
            {
                "id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/1"
                    }
                }
            },
            {
                "id": 3916883,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/3916883"
                    }
                }
            }
        ],
        "customers": [
            {
                "id": 134923,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134923"
                    }
                }
            }
        ],
        "catalog_elements": [],
        "companies": [
            {
                "id": 1,
                "_links": {
                    "self": {
                        "href": "https://example. amocrm.ru/api/v4/companies/1"
                    }
                }
            }
        ]
    }
}
Параметры для GET-параметры with

ПараметрОписание
catalog_elementsДобавляет в ответ связанные с контактами элементы списков
leadsДобавляет в ответ связанные с контактами сделки
customersДобавляет в ответ связанных с контактами покупателей

Добавление контактов

Метод

POST /api/v4/contacts

Описание

Метод позволяет добавлять контакты в аккаунт пакетно.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют

ПараметрТип данныхОписание
namestringНазвание контакта
first_namestringИмя контакта
last_namestringФамилия контакта
responsible_user_idintID пользователя, ответственного за контакт
created_byintID пользователя, создавший контакт
updated_byintID пользователя, изменивший контакт
created_atintДата создания контакта, передается в Unix Timestamp
updated_atintДата изменения контакта, передается в Unix Timestamp
custom_fields_valuesarrayМассив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта. Примеры заполнения полей
_embeddedobjectДанные вложенных сущностей
_embedded[tags]arrayДанные тегов, привязанных к контакту
_embedded[tags][0]objectМодель тега, привязанного к контакту
_embedded[tags][0][id]intID тега
_embedded[tags][0][name]stringНазвание тега
request_idstringПоле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным
Пример запроса
[
    {
        "first_name": "Петр",
        "last_name": "Смирнов",
        "custom_fields_values": [
            {
                "field_id": 271316,
                "values": [
                    {
                        "value": "Директор"
                    }
                ]
            }
        ]
    },
    {
        "name": "Владимир Смирнов",
        "created_by": 47272
    }
]
Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответаУсловие
200Контакты были успешно созданы
401Пользователь не авторизован
400Переданы некорректные данные. Подробности доступны в теле ответа
Параметры ответа

Метод возвращает коллекцию контактов, которые были созданы.

ПараметрТип данныхОписание
idintID контакта
request_idstringСтрока переданная при запросе или порядковый указатель, если параметр не передан
Пример ответа
{
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/contacts"
    }
  },
  "_embedded": {
    "contacts": [
      {
        "id": 40401635,
        "request_id": "0",
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts/40401635"
          }
        }
      },
      {
        "id": 40401636,
        "request_id": "1",
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts/40401636"
          }
        }
      }
    ]
  }
}

Редактирование контактов

Метод

PATCH /api/v4/contacts

Описание

Метод позволяет редактировать контакты пакетно.
Также вы можете добавить ID контакта в метод для редактирования конкретного контакта (/api/v4/contacts/{id}).
При редактировании пакетно передается массив из объектов-контактов, при редактировании одного контакта, передается просто модель контакта.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют

ПараметрТип данныхОписание
namestringНазвание контакта
first_namestringИмя контакта
last_namestringФамилия контакта
responsible_user_idintID пользователя, ответственного за контакт
created_byintID пользователя, создавший контакт
updated_byintID пользователя, изменивший контакт
created_atintДата создания контакта, передается в Unix Timestamp
updated_atintДата изменения контакта, передается в Unix Timestamp
custom_fields_valuesarrayМассив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта. Примеры заполнения полей
_embeddedobjectДанные вложенных сущностей
_embedded[tags]arrayДанные тегов, привязанных к контакту
_embedded[tags][0]objectМодель тега, привязанного к контакту
_embedded[tags][0][id]intID тега
_embedded[tags][0][name]stringНазвание тега
Пример запроса
[
    {
        "id": 3,
        "first_name": "Иван",
        "last_name": "Иванов",
        "custom_fields_values": [
            {
                "field_id": 66192,
                "field_name": "Телефон",
                "values": [
                    {
                        "value": "79999999999",
                        "enum_code": "WORK"
                    }
                ]
            }
       ]
    }
]
Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответаУсловие
200Контакты были успешно изменены
401Пользователь не авторизован
400Переданы некорректные данные. Подробности доступны в теле ответа
Параметры ответа

Метод возвращает коллекцию контактов, которые были изменены.

ПараметрТип данныхОписание
idintID контакта
updated_atintUnix Timestamp изменения контакта
Пример ответа
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 3,
                "name": "Иван Иванов",
                "updated_at": 1590945248,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/3"
                    }
                }
            }
        ]
    }
}

Привязка чатов к контактам

Метод

POST /api/v4/contacts/chats

Описание

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

Ограничения

Метод доступен с правами администратора аккаунта.
В настройках канала должен быть указан uuid интеграции, которая запрашивает метод.
Интеграция может менять привязку чатов только по каналам, к которым она имеет доступ.
Не должны передаваться никакие сессионые куки, иначе метод вернет ошибку.

Заголовок запроса

Content-Type: application/json

Параметры запроса

ПараметрТип данныхОписание
chat_idstringДанный параметр принимает массив строк, uuid идентификаторов чатов
contact_idintДанный параметр принимает массив чисел, id контактов
request_idstringПоле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным
Пример запроса
[
    {
        "contact_id": 3102959,
        "chat_id":"6cbab3d5-c4c1-46ff-b710-ad59ad10805f"
    }
]
Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответаУсловие
200Запрос выполнен успешно
401Пользователь не авторизован
Параметры ответа

Метод возвращает коллекцию связей

ПараметрТип данныхОписание
idintID связи контакта и чата (может меняться при изменении привязки чата к контакту)
contact_idintID контакта
chat_idstringID чата
request_idstringСтрока переданная при запросе или порядковый указатель, если параметр не передан
Пример ответа
{
    "_total_items": 1,
    "_embedded": {
        "chats": [
            {
                "chat_id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
                "contact_id": 3102959,
                "id": 26219,
                "request_id": "0"
            }
        ]
    }
}

Получение списка чатов контакта

Метод

GET /api/v4/contacts/chats

Описание

Метод позволяет получить список чатов, которые относятся к контактам. Или список контактов к которым привязан чат.
Если чат относится к неразобранному, метод вернет id контакта в этом неразобранном.

Ограничения

Метод доступен с правами администратора аккаунта.
В настройках канала должен быть указан uuid интеграции, которая запрашивает метод.
Интеграция может запросить только чаты по каналам, к которым она имеет доступ. Таким образом внутренние чаты между пользователями аккаунта выводится не будут.
Не должны передаваться никакие сессионые куки, иначе метод вернет ошибку.

GET параметры

ПараметрТип данныхОписание
chat_idstringДанный параметр принимает массив строк, uuid идентификаторов чатов
contact_idintДанный параметр принимает массив чисел, id контактов
Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответаУсловие
200Запрос выполнен успешно
401Пользователь не авторизован
400Переданы не верные данные в запросе. Подробности в теле ответа
Параметры ответа

Метод возвращает коллекцию связей

ПараметрТип данныхОписание
idintID связи контакта и чата (может меняться при изменении привязки чата к контакту)
contact_idintID контакта
chat_idstringID чата
Пример ответа
{
    "_total_items": 1,
    "_embedded": {
        "chats": [
            {
                "chat_id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
                "contact_id": 3102959,
                "id": 26219
            }
        ]
    }
}

PHP Developer Описание работы Март 2023

PHP-разработчик отвечает за написание логики веб-приложений на стороне сервера. Разработчики PHP обычно разрабатывают внутренние компоненты, связывают приложение с другими (часто сторонними) веб-сервисами и поддерживают разработчиков внешнего интерфейса, интегрируя их работу с приложением. Они также часто требуются для разработки и интеграции плагинов для некоторых популярных фреймворков.

Написание хорошего описания работы и рекламы PHP-разработчика требует внимания к деталям. Когда вы ищете продвинутого веб-разработчика PHP, размещение общего описания веб-разработчика в объявлении о вакансии приведет к многочисленным откликам от людей, которые могут иметь мало знаний о передовых методах программирования.

PHP — это язык, который трудно укротить, и он возлагает на разработчика большую, чем обычно, нагрузку по обеспечению стабильности и производительности приложения. В этой статье вы найдете образец описания вакансии PHP-разработчика, который поможет вам составить идеальное объявление о вакансии и гарантирует, что вы легко найдете и наймете человека, соответствующего вашим конкретным критериям.

Разработчик PHP — описание работы и шаблон объявления

Скопируйте этот шаблон и измените его как свой собственный:

Введение в компанию

{{Напишите короткий и запоминающийся абзац о своей компании. Обязательно предоставьте информацию о культуре компании, преимуществах и преимуществах. Укажите часы работы, возможности удаленной работы и все остальное, что, по вашему мнению, делает вашу компанию интересной.}}

Описание вакансии

Мы ищем разработчика PHP, отвечающего за управление серверными службами и обмен данными между сервер и пользователи. Ваша основная задача будет заключаться в разработке всей серверной логики, определении и обслуживании центральной базы данных, а также в обеспечении высокой производительности и скорости реагирования на запросы внешнего интерфейса. Вы также будете нести ответственность за интеграцию интерфейсных элементов, созданных вашими коллегами, в приложение. Следовательно, базовое понимание фронтенд-технологий также необходимо.

Обязанности

  • Интеграция пользовательских элементов, разработанных фронтенд-разработчиками
  • Создавайте эффективные, тестируемые и повторно используемые модули PHP
  • Решение сложных проблем производительности и архитектурных задач
  • Интеграция решений для хранения данных {{может включать базы данных, хранилища ключей и значений, хранилища BLOB-объектов и т.  д.}}
  • {{Добавьте сюда другие важные обязанности}}

Навыки и квалификации

  • Хорошее знание веб-фреймворков PHP {{таких как Laravel, Yii и т. д., в зависимости от вашего стека технологий}}
  • Понимание полностью синхронного поведения PHP
  • Понимание шаблонов проектирования MVC
  • Базовое понимание интерфейсных технологий, таких как JavaScript, HTML5 и CSS3
  • Знание объектно-ориентированного программирования PHP
  • Общие сведения о доступности и соответствии требованиям безопасности {{В зависимости от конкретного проекта}}
  • Хорошее знание распространенных эксплойтов PHP или веб-сервера и их решений
  • Понимание фундаментальных принципов проектирования масштабируемого приложения
  • Проверка подлинности и авторизация пользователей между несколькими системами, серверами и средами
  • Интеграция нескольких источников данных и баз данных в одну систему
  • Знакомство с ограничениями PHP как платформы и обходными путями
  • Создание схем базы данных, которые представляют и поддерживают бизнес-процессы
  • Знакомство с базами данных SQL/NoSQL и их декларативными языками запросов
  • Хорошее понимание инструментов управления версиями кода, таких как Git
  • {{Обязательно укажите другие фреймворки, библиотеки или любые другие технологии, связанные с вашим стеком разработки}}
  • {{Укажите необходимый уровень образования или сертификации}}

См. также: Растущий, поддерживаемый сообществом список Toptal основных вопросов для собеседования по PHP

Последние статьи о PHP от Toptal Engineers

Просмотреть все публикации о PHP

10 основных типов вакансий разработчиков PHP с полным стеком

Посмотрите, какие роли, похожие на FULL Stack PHP Developer, сейчас нанимают

PHP-разработчик с полным стеком сочетает в себе навыки фронтенд- и бэкэнд-разработки, чтобы увидеть проект от начала до конца. В ваши должностные обязанности входит работа над всеми аспектами проекта программирования, чтобы удовлетворить все потребности и ожидания клиентов. У вас должен быть опыт работы с PHP, CSS, JavaScript и другими распространенными компьютерными языками. Дополнительные профессиональные квалификации включают добровольную сертификацию технологий, опыт управления данными и сильные организаторские способности. Для этой должности не требуется никакой степени, хотя степень бакалавра в области компьютерных наук или программирования поможет вам в поиске работы.

Если вас интересует работа, связанная с FULL Stack PHP Developer, вот несколько популярных поисковых запросов с наиболее открытыми вакансиями на ZipRecruiter.

Основные типы вакансий FULL Stack PHP Developer

  • PHP

    Диапазон заработной платы: 77 000–121 500 долларов США в год

    PHP — распространенный запрос для поиска работы. Большинство зарплат на PHP-работах составляют от 77 000 долларов (25-й процентиль) до 121 500 долларов (75-й процентиль) в год. По всей стране есть много открытых вакансий для поиска работы PHP, и сейчас на ZipRecruiter открыто около 14 000 вакансий.

    Просмотреть все вакансии PHP  

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

    Диапазон заработной платы: 67 500–104 000 долларов США в год

    PHP-разработчик разрабатывает и реализует серверные веб-программы с использованием языка программирования PHP. Этот язык существует в самых разных веб-приложениях, а его универсальность делает его подходящим для встраивания в HTML. Как разработчик PHP, вы отвечаете за разработку программ и приложений, а также веб-сайтов. В процессе написания в ваши обязанности также входит отладка и поддержка исходного кода на случай, если другим разработчикам потребуется внести изменения. Создание пользовательской документации — еще один аспект вашей работы в качестве PHP-разработчика.

    См. все вакансии PHP Developer  

  • PHP-программист

    Диапазон заработной платы: 48 500–73 000 долларов США в год

    Как программист PHP, ваша работа заключается в разработке программного обеспечения для использования с определенной операционной системой, такой как Windows или Linux. Когда вы пишете программу, вы можете публиковать ее в Интернете, конвертировать на другой язык или интегрировать в существующее программное обеспечение. Вы можете рассчитывать на то, что потратите некоторое время на проектирование, сборку, тестирование и отладку создаваемых вами приложений. Большая часть работы PHP сосредоточена на веб-приложениях и требует дополнительного кодирования в HTML, а также использования пакетов баз данных, таких как Oracle и MySQL. В ваши обязанности также входит быть в курсе последних изменений и рекомендаций по программированию.

    См. все вакансии PHP Programmer  

  • Разработчик PHP Python

    Диапазон заработной платы: 83 500–122 500 долларов США в год

    PHP Python Developer — более необычный запрос для поиска работы, но он все же может дать вам интересные результаты. Большинство зарплат для разработчиков PHP Python составляет от 83 500 долларов (25-й процентиль) до 122 500 долларов (75-й процентиль) в год. По всей стране есть много открытых вакансий для поиска работы PHP Python Developer, и сейчас на ZipRecruiter открыто около 6000 вакансий.

    См. все вакансии PHP Python Developer  

  • Разработчик PHP-приложений

    Диапазон заработной платы: 77 000–113 500 долларов США в год

    PHP Application Developer — более необычный запрос для поиска работы, но он все равно может дать вам интересные результаты. Большинство заработных плат для разработчиков приложений PHP составляет от 77 000 долларов (25-й процентиль) до 113 500 долларов (75-й процентиль) в год. По всей стране есть много открытых вакансий для разработчиков приложений PHP, и сейчас на ZipRecruiter открыто около 6000 вакансий.

    См. все  PHP Application Developer  вакансии

  • Архитектор PHP

    Диапазон заработной платы: 106 000–143 000 долларов в год

    Архитектор PHP специализируется на языке программирования PHP и работает с программными архитектурными шаблонами, включая Model View Controller (MVC) в рамках, для проектирования и разработки бизнес-решений. В ваши должностные обязанности как архитектора PHP может входить написание кода, тестирование и организация кода с использованием принципов программирования, а также настройка подключаемых модулей для приложений. Карьера обычно требует обширных знаний PHP и опыта разработки программного обеспечения. Дополнительные квалификации включают профессиональную сертификацию PHP, степень бакалавра в области, связанной с компьютером, и отличные технические и организационные навыки.

    Посмотреть все вакансии PHP Architect  

  • PHP-разработчик SQL

    Диапазон заработной платы: 76 500–115 000 долларов в год

    PHP SQL Developer — более необычный запрос для поиска работы, но он все равно может дать вам интересные результаты. Большинство заработных плат для разработчиков PHP SQL составляет от 76 500 долларов (25-й процентиль) до 115 000 долларов (75-й процентиль) в год. Вы найдете много открытых вакансий по всей стране для поиска работы PHP SQL Developer, и сейчас на ZipRecruiter доступно около 4000 вакансий.

    Просмотреть все вакансии PHP SQL Developer  

  • PHP Backend-разработчик

    Диапазон заработной платы: 77 500–98 500 долларов США в год

    PHP Backend Developer — более необычный запрос для поиска работы, но он все равно может дать вам интересные результаты. Большинство заработных плат для разработчиков PHP Backend составляют от 77 500 долларов (25-й процентиль) до 9 долларов.8500 (75-й процентиль) в год. Вы найдете много открытых вакансий по всей стране для поиска работы PHP Backend Developer, и сейчас на ZipRecruiter доступно около 3000 вакансий.

    См. все вакансии PHP Backend Developer  

  • Базовый PHP-разработчик

    Диапазон заработной платы: 74 000–122 000 долларов США в год

    Core PHP Developer — более необычный запрос для поиска работы, но он все равно может дать вам интересные результаты. Большинство зарплат на должностях Core PHP Developer составляют от 74 000 долларов (25-й процентиль) до 122 000 долларов (75-й процентиль) в год. Взгляните на множество открытых вакансий по всей стране для поиска работы Core PHP Developer, около 300 вакансий сейчас доступны на ZipRecruiter.

    См. все вакансии Core PHP Developer  

  • Нанять PHP-разработчика

    Диапазон заработной платы: 67 500–93 500 долларов США в год

    Hire PHP Developer — более необычный запрос для поиска работы, но он все равно может дать вам интересные результаты. Большинство заработных плат по найму разработчиков PHP составляет от 67 500 долларов (25-й процентиль) до 93 500 долларов (75-й процентиль) в год. Взгляните на множество открытых вакансий по всей стране для поиска работы Hire PHP Developer, около 200 вакансий сейчас доступны на ZipRecruiter.

    См. все  Hire PHP Developer  вакансии

Получайте новые вакансии ежедневно по электронной почте

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *