Построение безопасных и удобных RESTful API - это одна из тех задач, которые доставляют разработчикам много головной боли. REST API уже давно являются отраслевым стандартом для обеспечения коммуникации между серверной и клиентской частями приложений.

Наша команда понимает важность хорошо спроектированного API и собрала лучшие практики, чтобы помочь разработчикам создать безупречное REST API.

Давайте поделимся всеми деталями через наиболее значимые сведения!

Советы по созданию лучшего REST API

Некоторые из наиболее распространенных ошибок, которые совершают разработчики при попытке создать REST API:

• Плохо написанная документация
• Неопределенная архитектура
• Несогласованные определения конечных точек
• Непонятная коммуникация
• Слабые меры безопасности

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

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

1. Возьмите документацию всерьез

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

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

К счастью, в настоящее время намного проще создавать документацию. Инструменты, такие как Apiary, Swagger, Raml и многие другие, помогают разработчикам генерировать документацию мгновенно. Вы всегда можете черпать вдохновение из полезной и хорошо написанной документации, такой как The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS или Moment.js.

2. Уделите внимание безопасности

Всегда старайтесь сохранять коммуникацию между клиентом и сервером конфиденциальной.

Разработчики используют API для создания своих сервисов и передачи данных. Если API сломан, подвергается угрозе или имеет серьезные утечки данных, он определенно не будет выбран ни одним разработчиком.

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

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

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

3. Выберите подходящий формат данных для поддержки

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

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

Прямые форматы данных - это лучший вариант при взаимодействии с другими API. Некоторые из наиболее часто используемых форматов - это JSON, YAML и XML.

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

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

4. Используйте пагинацию

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

Мы рекомендуем использовать стандартный лимит для возвращаемых данных и параметры, такие как limit и offset, вот так: /users?limit=30&offset=60.

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

5. Создавайте версии для каждой основной функции

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

Давайте рассмотрим несколько примеров того, как можно версионировать API:

• Разместите номер версии непосредственно в URL-адресе API: api.example.com/v1/users
• Установите пользовательские заголовки, чтобы включить номер версии API: **curl -H “API-version: 1.0” **https://api.example.com/users
• Измените заголовок accept, чтобы включить номер версии API: **curl -H “Accept: application/vnd.example.v1+json” **https://api.example.com/users
• Добавьте номер версии в качестве параметра запроса: https://api.example.com/users?version=1

6. Используйте правильные методы и коды HTTP

RESTful API имеет четыре метода для указания того, что разработчики будут делать с переданными данными.

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

• GET - Используйте этот метод каждый раз, когда вам нужно получить ресурс или коллекцию ресурсов.
• POST - Разработчики должны использовать его каждый раз, когда им нужно создать новый ресурс или коллекцию ресурсов.
• PUT - Этот метод используется для обновления конкретной информации.
• DELETE - Это довольно очевидно. Он помогает нам удалить существующие ресурсы или коллекцию ресурсов.

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

• 200 OK - Это самый распространенный код, с которым мы сталкиваемся как разработчики. Или по крайней мере, мы надеемся на это. Он представляется нам, когда операция выполнилась успешно.
• 201 CREATED - Ранее представленный метод POST идет рука об руку с этим кодом HTTP, так как он должен оповещать клиента, что ресурс успешно создан.
• 400 BAD REQUEST - Это код HTTP, который появится, когда запрос не выполнен успешно.
• 401 UNAUTHORIZED - Если нам нужно ограничить доступ пользователя к части нашего приложения, это должен быть код HTTP, который мы отправляем вместе с сообщением об ошибке.
• 404 NOT FOUND - Самый распространенный код HTTP во всем интернете. Даже люди, не изучавшие разработку программного обеспечения, знают, что код HTTP 404 означает, что ресурсы не найдены.
• 500 INTERNAL SERVER ERROR - Следует возвращать эту ошибку, когда сервер не может ответить.

Как видите, все коды HTTP довольно очевидны. Использование каждого из них при необходимости может сэкономить много времени в долгосрочной перспективе.

7. Убедитесь, что сообщения об ошибках понятны

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

Мы должны выбрасывать правильные сообщения об ошибках и наиболее явные коды ошибок HTTP, чтобы устранить эту путаницу.

Например, если пользователь хочет создать новую учетную запись, но электронная почта уже используется на платформе, мы должны вернуть код HTTP 400 с сообщением "Email already exists" (Электронная почта уже существует). Таким образом, мы избегаем обработки большого количества запросов, потому что пользователь будет знать, в чем проблема, и не будет принуждать к регистрации.

Как выглядит эффективный REST API?

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

Однако, если у вас нет времени и терпения создавать API для ваших проектов парсинга, почему бы не воспользоваться готовым решением. Наша команда приложила усилия, чтобы создать одно из самых безопасных и легко используемых API для парсинга. Это только некоторые из основных принципов, которые они использовали, чтобы гарантировать отсутствие утечек данных или простоя API.

Если вы хотите попробовать, вы можете получить 1000 вызовов API, создав бесплатную учетную запись и протестировав одно из самых успешных API для парсинга.

Начните свое путешествие по парсингу прямо сейчас!