Заметки с тегом «web»

Шпаргалка по созданию RESTful API

RESTful API может создаваться не только для сторонних сервисов. Он может использоваться одностраничными приложениями для работы с бэк-эндом. Вот несколько основных моментов, которые нужно знать при проектировании интерфейса.

URLs и действия

Ключевым принципом REST является деление вашего API на логические ресурсы. Управление этими ресурсами происходит с помощью HTTP-запросов с соответствующим методом — GET, POST, PUT, PATCH, DELETE.

Ресурс должен описываться существительным во множественном числе. Действия над ресурсами, обычно, определяются стратегией CRUD и соответствуют HTTP-методам следующим образом:

  • GET /api/users — получить список пользователей;
  • GET /api/users/123 — получить указанного пользователя;
  • POST /api/users — создать нового пользователя;
  • PUT /api/users/123 — обновить все данные указанного пользователя;
  • PATCH /api/users/123 — частично обновить данные пользователя;
  • DELETE /api/users/123 — удалить пользователя.

Если ресурс существует только в контексте другого ресурса, то URL может быть составным:

  • GET /api/posts/9/comments — получить список комментариев к записи №9;
  • GET /api/posts/9/comments/3 — получить комментарий №3 к записи №9.

Когда действие над объектом не соответствует CRUD операции, то его можно рассматривать как составной ресурс:

  • POST /api/posts/9/like — отметить запись №9 как понравившуюся;
  • DELETE /api/posts/9/like — снять отметку «понравилось» с записи №9.

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

Методы POST, PUT или PATCH могут изменять поля ресурса, которые не были включены в запрос (например, ID, дата создания или дата обновления). Чтобы не вынуждать пользователя API выполнять ещё один запрос на получение обновлённых данных, такие методы должны вернуть их в ответе.

Фильтры, сортировка и поиск

Любые параметры в HTTP-запросе могут быть использованы для уточнения запроса или сортировки данных.

  • GET /api/users?state=active — список активных пользователей;
  • GET /api/tasks?state=open&sort=priority,-created_at — список невыполненных задач, отсортированных по приоритету и дате создания (сперва новые задачи).

Постраничная навигация

Когда нужно в ответ на запрос списка объектов добавить информацию о постраничной навигации, стоит воспользоваться HTTP-заголовком Link, а не добавлять обёртки данным.

Пример заголовка:

Link: <http://domain.tld/api/users?page=5&per_page=100>; rel="next",
    <http://domain.tld/api/users?page=3&per_page=100>; rel="prev",
    <http://domain.tld/api/users?page=1&per_page=100>; rel="first",
    <http://domain.tld/api/users?page=10&per_page=100>; rel="last"

Возможные значения rel:

  • next — следующая страница результатов;
  • prev — предыдущая страница результатов;
  • first — первая страница результатов;
  • last — последняя страница результатов.

Важно следовать этим значениям, а не конструировать собственные URL-ы потому, что иногда постраничная навигация может основываться на сложных правилах, а не простом переборе страниц.

Переопределение HTTP-метода

Для совместимости с некоторыми серверами или клиентами, которые не поддерживают другие HTTP-методы кроме GET и POST, может быть полезным их эмуляция. Значение метода передаётся в заголовке X-HTTP-Method-Override, а сам он выполняется как POST-метод. GET-запросы не должны менять состояние сервера!

Коды HTTP-статуса

  • 200 OK — ответ на успешный запрос GET, PUT, PATCH или DELETE.
  • 201 Created — ответ на POST запрос, в результате которого произошло создание нового объекта. Ответ так же должен сопровождаться заголовком Location, указывающий на URL ресурса.
  • 204 No Content — ответ на успешно выполненный запрос, который ничего не возвращает (например, DELETE).
  • 404 Not Found — запрашиваемый объект не найден.
  • 500 Internal Server Error — ошибка на сервере.

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

Метаданные

Любые данные, которые лишь опосредованно относятся к результату запроса, но могут быть полезны клиенту, стоит отдавать в виде HTTP-заголовков. Создание обёрток над данными ломает совместимость с принципами REST.

Оставте свой комментарий

Отчёт о поездке на конференцию Fronteers

4 и 5 октября 2012 года в Амстердаме проходила ежегодная международная конференция для веб-разработчиков Fronteers и мне удалось побывать на ней.

В нашей компании после поездки принято делать краткие отчёты-презентации. Для такого отчёта я подготовил слайды с тезисами и ссылками на презентации докладчиков.

Оставте свой комментарий

JavaScript фреймворки. Куда катится мир

Уже становится традицией, что в последние выходные февраля в Челябинск проходит слёт профессионалов, чья работа хоть как-то связана с вебом.

В этом году я представил уважаемой публике доклад на тему «JavaScript фреймворки. Куда катится мир». Хотел опубликовать слайды к докладу вместе с видео. Но, похоже, в этом году его не будет.

Итак, слайды с комментариями или в формате PDF.

Оставте свой комментарий

Позиционируем всё

Конференция уральских веб-разработчиков 2011

В феврале 2011 года прошла уже вторая по счёту Конференция уральских веб-разработчиков, на которой я выступил с докладом «Позиционируем всё»

Презентация доклада (PDF, 2Мб)

  • Закладываем надежный фундамент для будущих страниц. Краткий обзор популярных «обнуляторов» стилей.
  • Техники позиционирования элементов (CSS-свойство position, плавающие блоки, отрицательный отступ и многое другое).
  • Планируем разметку. Не забываем включать голову, и думать на шаг вперед.
  • Как угодить и дизайнеру и оптимизатору.
 
Комментарии к заметке: 1

О пользе карты сайта

Карта сайта (Sitemap) — это XML-файл с информацией о страницах сайта, которые нужно проиндексировать поисковым системам. Поисковые системы могут обнаружить все страницы сайта, на которые есть ссылки, но с помощью карты сайта ему эта информация предоставляется в явном виде. В этом файле указывается местонахождение страниц сайта, время их последнего обновления, частоту обновления и важность относительно других страниц сайта для того.

Например, Sitemap может быть таким:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>http://noteskeeper.ru/</loc>
        <lastmod>2010-03-20</lastmod>
        <changefreq>daily</changefreq>
        <priority>1</priority>
    </url>
</urlset>

Спецификацию протокола можно найти на сайте sitemaps.org

Как альтернатива карте сайта может использоваться канал синдикации RSS или ATOM. Однако на практике в этих файлах передаются далеко не все страницы.

Оставте свой комментарий