Интерфейс rest: REST API — Основы Веб-программирования

REST API — Основы Веб-программирования

REST API подразумевает под собой простые правила:

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

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

Pattern matching

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

from wsgiref.simple_server import make_server

from pyramid.view import view_config, view_defaults
from pyramid.config import Configurator


@view_defaults(
    route_name='rest_people',
    renderer='json'
)
class RESTViewPeople(object):
    def __init__(self, request):
        self.request = request

    @view_config(request_method='GET')
    def get(self):
        return {
            'id': self.request.matchdict['id'],
            'method': self.request.method,
            'get': dict(self.request.GET)
        }

    @view_config(request_method='POST')
    def post(self):
        return {
            'id': self.request.matchdict['id'],
            'method': self.request.method,
            'post': dict(self.request.POST)
        }

    @view_config(request_method='DELETE')
    def delete(self):
        return {'status': 'success'}


if __name__ == '__main__':
    config = Configurator()
    config.add_route('rest_people', '/api/v1/people/{id:\d+}')
    config.add_view(RESTViewPeople, route_name='rest_people')
    config.scan('.')

    # make wsgi app
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

Пример выше добавляет View с тремя методами, каждый из которых вызывается при
соответствующем GET, POST, DELETE запросе.
Ресурсом здесь является конкретный человек, получить которого можно по URL
http://localhost:8080/api/v1/people/123

Результатом запроса будет:

{"get": {}, "id": "123", "method": "GET"}

Для отправки POST запроса воспользуемся консольной утилитой curl:

$ curl -X POST -d 'param1=value1&param2=value2' http://localhost:8080/api/v1/people/1

Результат запроса:

{"id": "1", "post": {"param1": "value1", "param2": "value2"}, "method": "POST"}

DELETE запрос выполняется по аналогии:

$ curl -X DELETE http://localhost:8080/api/v1/people/1

Результат запроса:

Traversal

См.также

Метод URL диспетчеризации Traversal

В предыдущем примере показан только один ресурс — конкретный человек и
в принципе все выглядит неплохо, пока не появится другой смежный ресурс,
например список всех людей по адресу http://localhost:8080/api/v1/people

В этом случае, придется добавлять новый путь (rout), привязывать его к
представлению (View) и самое неприятное менять само представление, или еще
хуже писать новое. Таким образом с увеличением ресурсов, сложность REST API
растет не пропорционально и в какой то момент код становится не читаемым
из-за больших размеров и постоянно меняющейся логики во View.

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

Ресурсы

Ресурсы могут выглядеть так:

Список всех людей

class PeopleResource(object):

    def __getitem__(self, people_id):
        if str(people_id).isdigit():
            return PersonResource(people_id)

    def __json__(self, request):
        return {
            'params': request.matchdict,
            'method': request.method,
        }

PeopleResource представляет список всех людей и будет доступен по
адресу http://localhost:8080/api/v1/people.
PeopleResource имеет метод __getitem__, что делает его похожим на
словарь. При обращении к объекту ресурса как к словарю, он вызовет
эту функцию и передаст ключ в параметр people_id, например:

foo = PeopleResource()
bar = foo[123]  # Вернет объект PersonResource(123)

Метод __json__ определяет каким образом преобразовывать ресурс в json.

PersonResource представляет конкретного человека и будет доступен по
адресу http://localhost:8080/api/v1/people/{id}. Здесь отличительной
особенностью является то, что метод __json__ наследует часть словаря из
класса PeopleResource, при помощи конструкции super:

Конкретный человек

class PersonResource(PeopleResource):

    def __init__(self, people_id):
        self.id = people_id

    def __json__(self, request):
        return {
            'id': self.id,
            **super().__json__(request)
        }

View

Перепишем View таким образом, чтобы она возвращала только ресурс, а так-как
ресурс уже содержит в себе информацию как отдавать json, то это представление
будет универсальным как для PeopleResource, так и для PersonResource
и возможно подойдет другим ресурсам которые мы будем писать в будущем.

Представление (View) для traversal ресурсов

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

@view_defaults(
    route_name='rest_api',
    renderer='json',
    context=PeopleResource
)
class RESTViewPeople(object):
    def __init__(self, context, request):
        self.context = context
        self.request = request

    @view_config(request_method='GET')
    def get(self):
        return self.context

    @view_config(request_method='POST')
    def post(self):
        return self.context

    @view_config(request_method='DELETE')
    def delete(self):
        return {'status': 'success'}

Рендерер json по умолчанию ищет метод __json__ и если он есть то
возвращает его результат вызова.

Route

Путь, в нашем случае, будет один, так-как вся структура вынесена в ресурсы
(метод __getitem__).

config.add_route('rest_api', '/api/v1/*traverse', factory=rest_factory)

Полный пример

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

from wsgiref.simple_server import make_server

from pyramid.view import view_config, view_defaults
from pyramid.config import Configurator


class PeopleResource(object):

    def __getitem__(self, people_id):
        if str(people_id).isdigit():
            return PersonResource(people_id)

    def __json__(self, request):
        return {
            'params': request.matchdict,
            'method': request.method,
        }


class PersonResource(PeopleResource):

    def __init__(self, people_id):
        self.id = people_id

    def __json__(self, request):
        return {
            'id': self.id,
            **super().__json__(request)
        }


class AnimalsResource(object):
    pass


@view_defaults(
    route_name='rest_api',
    renderer='json',
    context=PeopleResource
)
class RESTViewPeople(object):
    def __init__(self, context, request):
        self.context = context
        self.request = request

    @view_config(request_method='GET')
    def get(self):
        return self.context

    @view_config(request_method='POST')
    def post(self):
        return self.context

    @view_config(request_method='DELETE')
    def delete(self):
        return {'status': 'success'}


def rest_factory(request):
    return {
        'people': PeopleResource(),
        'animals': AnimalsResource(),
    }


if __name__ == '__main__':
    config = Configurator()
    config.add_route('rest_api', '/api/v1/*traverse', factory=rest_factory)
    config.add_view(RESTViewPeople, route_name='rest_api')
    config. scan('.')

    # make wsgi app
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

Что такое REST?

Единый интерфейс определяет интерфейс между клиентами и серверами.
Это упрощает и отделяет архитектуру, которая позволяет каждой части развиваться самостоятельно.
Четыре принципа единого интерфейса:

Основан на ресурсах

Отдельные ресурсы определяются в запросе, для чего используется URI, как идентификаторы ресурсов.
Сами ресурсы концептуально отделены от представлений, которые возвращаются клиенту.
Например, сервер не отправляет свою базу данных, а, скорее, некоторые HTML, XML или JSON,
которые представляет некоторые записи в базе данных, например, на финском языке и в UTF-8,
в зависимости от деталей запроса и реализации сервера.

Манипуляции над ресурсами через представления

Когда пользователь имеет представление о ресурсе, в том числе о связанных метаданных, он имеет достаточно информации для изменения или
удаления ресурса на сервере, если у него есть на это разрешение

Само-документируемые сообщения

Каждое сообщение содержит достаточно информации для описания того, как его выполнить.
Например, вызываемый парсер может описываться с помощью Internet media type (так же известным как MIME)
Ответы также явно указывают на их способность кешировать.

Hypermedia as the Engine of Application State (HATEOAS)

Клиенты предоставляют статус через содержимое body, параметры строки запроса, заголовки запросов и запрашиваемый URI (имя ресурса).
Это называется гипермедиа (или гиперссылки с гипертекстом)

Наряду с приведенным выше описанием, HATEOS также означает, что, в случае необходимости
ссылки содержатся в теле ответа (или заголовках) для поддержки URI извлечения самого объекта или запрошенных объектов.
Позднее, мы затронем эту тему глубже.

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

Здесь вместо REST возвращает API-интерфейсы веб-интерфейс на json

Я оцениваю HERE мест APIs. Однако url возвращает веб-страницу вместо обычного JSON в качестве ответа. Пример запроса:

https://places.cit.api.here.com/places/v1/autosuggest?app_id={YOUR_APP_ID}&app_code{YOUR_APP_CODE}&at=52.5304417,13.4111201&q=rest&pretty

Мне нужен ответ как простой JSON, но я не могу найти никакой информации на странице документации .

here-api

Поделиться

Источник

SW Developers    

07 мая 2018 в 18:27

3 ответа

• REST API с заголовком Accept application / json возвращает число

  Вопрос Новичка: У меня есть rest api в моем приложении: https://hostname/app-rest/session/manager/active-session/count . The API возвращает количество сеансов с определенными атрибутами, такими как тип соединения, статус и т. д. Когда я устанавливаю заголовок запроса Content-Type: application/json…

• REST — Rails API интерфейс

  Я хочу создать приложение Rails + React.JS , и я видел, что большинство учебников в интернете упоминают о REST API. Данные, которые я хочу получить через JSON Я понимаю, что такое REST API, но чего я не понимаю, так это как интерфейс обслуживается пользователю? Нужно ли мне иметь 2 проекта Rails ,…

1

Ответ заключается в том, чтобы добавить параметр обратного вызова к url. Пример:

https://places.cit.api.here.com/places/v1/autosuggest?app_id={YOUR_APP_ID}&app_code{YOUR_APP_CODE}&at=52.5304417,13. 4111201&q=rest&pretty&callback=xyz

Это не ясно из документации. Я получил эту информацию от службы поддержки HERE.

Поделиться

SW Developers    

09 мая 2018 в 08:43

1

Это происходит потому , что вы пытались выполнить запрос из адресной строки вашего браузера, и в этом случае браузер автоматически добавляет Accept: text/html к заголовкам запроса⁽1⁾.

Затем, поскольку Places API имеет некоторый веб-вспомогательный инструмент для игры с доступными параметрами, он возвращает html (веб-UI), потому что Accept: text/html был найден в заголовках запроса.

Решение добавить callback -это скорее обходной путь, так как оно обертывает ответ значением параметра обратного вызова.

Ваш первоначальный запрос был действительно действителен. Если вы отправляете его из своей программы или клиента REST, например Postman, а не из браузера, вы фактически получаете JSON по умолчанию, так что больше делать было нечего. Конечно, вы можете явно отправить заголовок Accept: application/json , чтобы быть в безопасности.

[1] Откройте сетевую панель инструментов разработчика браузера, чтобы увидеть, что отправляется.

Поделиться

Michael P. Bazos    

20 мая 2018 в 13:53

0

Вы должны установить заголовок Accept , чтобы служба отвечала в JSON.

См. пример в документации здесь :

curl \
  -X GET \
  -H 'Accept: application/json' \
  --get 'https://places.demo.api.here.com/places/v1/discover/search' \
    --data-urlencode 'at=37.7942,-122.4070' \
    --data-urlencode 'q=restaurant' \
    --data-urlencode 'app_id={YOUR_APP_ID}' \
    --data-urlencode 'app_code={YOUR_APP_CODE}'

Поделиться

zero298    

07 мая 2018 в 18:35

• Fetch -API возвращает HTML вместо JSON

  У меня есть Spring REST API, который я тестировал на Postman, и он возвращает совершенно действительный JSON. Однако когда я вызываю тот же самый API в своем интерфейсном коде React, он возвращает HTML. Это функция, которую я использую для вызова API, export function run(engine, mediaId, owner,…

• Веб-интерфейс для службы REST api в spring-boot

  У меня есть приложение spring boot, где я создал RESTful api, используя @RestController,, что позволяет мне поддерживать список устройств (add/delete/update) в бэкэнде mysql. Сейчас я пытаюсь создать веб-интерфейс, который позволяет мне использовать этот API и нашел Spring MVC + Thymeleaf…

Похожие вопросы:

что такое интерфейс JSON REST

Есть ли какой-нибудь учебник по интерфейсу JSON RESTful (с использованием сервлета JAVA)? Цель состоит в том, чтобы вызвать внешний интерфейс REST для получения данных и обработать данные…

Java REST интерфейс

У меня есть среда веб-приложений PHP. Я использую Slim Framework в качестве интерфейса REST для своего приложения. Мой интерфейс приложения написан с использованием Backbone.js и jQuery. Существует…

Как построить клиентский интерфейс REST для бэкенда REST API?

Я построил бэкэнд REST API с использованием Django и сейчас нахожусь на стадии проектирования клиентского интерфейса. Хотя, кажется, я не могу понять, как должен быть структурирован этот клиентский…

REST API с заголовком Accept application / json возвращает число

Вопрос Новичка: У меня есть rest api в моем приложении: https://hostname/app-rest/session/manager/active-session/count . The API возвращает количество сеансов с определенными атрибутами, такими как…

REST — Rails API интерфейс

Я хочу создать приложение Rails + React.JS , и я видел, что большинство учебников в интернете упоминают о REST API. Данные, которые я хочу получить через JSON Я понимаю, что такое REST API, но чего. ..

Fetch -API возвращает HTML вместо JSON

У меня есть Spring REST API, который я тестировал на Postman, и он возвращает совершенно действительный JSON. Однако когда я вызываю тот же самый API в своем интерфейсном коде React, он возвращает…

Веб-интерфейс для службы REST api в spring-boot

У меня есть приложение spring boot, где я создал RESTful api, используя @RestController,, что позволяет мне поддерживать список устройств (add/delete/update) в бэкэнде mysql. Сейчас я пытаюсь…

Rest веб-служба не возвращает массив JSON

При вызове веб-службы, если ответом является список, содержащий один элемент, веб-служба REST возвращает объект JSON вместо массива JSON. Как я могу всегда возвращать массив? @GET…

Реализовать REST API и веб-интерфейс в Django

Существует ли правильный / правильный подход к реализации RESTful API и пользовательского интерфейса, который использует этот API в Django? У меня есть приложение, для которого я хотел бы создать…

Django возврат веб-страницы вместо JSON

Я довольно новичок в Django и пытаюсь реализовать базовый REST API в Django. У меня есть список новостей в базе данных MySQL, и после различных учебных пособий мне успешно удалось реализовать…

Что такое REST API

Назад

Что такое REST?

REST это:

• Определенно не HTTP
• Не протокол
• Не спецификация

Вот почему вокруг REST APIs так много споров.

И всё-таки…

REST это стиль архитектуры.

О, хорошо… но что такое стиль архитектуры?

Стиль архитектуры

Желаемая архитектура

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

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

REST выступает за представление состояния передачи

Это было записано Роем Филдингом в его докторской диссертации в 2000 году, где он описал существующую и современную веб-архитектуру как абстракцию.

Название было призвано вызывать представление о том, как ведет себя хорошо разработанное веб-приложение.

Рой описал REST на простом примере:

Рассмотрим сеть веб-страниц как виртуальную машину состояний.

Каждая страница представляет состояние:

1. Во-первых, пользователь получает первое состояние в виде индексного состояния.

2. Затем пользователь переходит через приложение, выбирая ссылку (здесь ссылка на страницу)

3. Результат передачи следующего состояния пользователю.

REST все еще не HTTP

Конечно, еще в 2000 году сеть уже работала на HTTP, и Рой со своими коллегами-инженерами много работали над этим.

Однако REST не определяет конкретные детали реализации системы и не определяет какой-либо синтаксис протокола.

Вполне возможно иметь архитектуру RESTful поверх протоколов, отличных от HTTP.

Например, CoAP (протокол ограниченного применения) является протоколом RESTful для встроенных устройств (Internet of Things) и предназначен для использования минимальных ресурсов как на устройстве, так и в сети.

Так зачем использовать REST?

Всемирная паутина основана на архитектуре REST.

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

Это важно отметить, поскольку не-RESTful API может быть неоптимальным в сетевой архитектуре, но оптимальным для других проблем. Например, современные интерфейсные приложения могут иметь очень специфические потребности, следовательно, растет число библиотек сбора данных, таких как GraphQL или Falcor.

Итак, когда это API RESTful?

API является RESTful, когда он постоянно действует под ограничениями REST.

REST определяет 6 ограничений для достижения желаемой оптимизации системы:

1. Клиент-сервер

Это ограничение основано на принципе разделения интересов.

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

2. Без гражданства

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

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

3. Кэш

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

Когда мы создаем наш API, он не должен игнорировать кеширование.

4. Правильный интерфейс

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

4.1. Идентификация ресурсов

Это означает, что любая информация, которая может быть названа, может быть ресурсом (изображение, документ или даже набор других ресурсов)

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

Ресурс может быть представлен различными способами.

Например, HTML, XML, JSON или даже JPEG-файл.

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

4.3 В-третьих, самоописательные сообщения

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

4.4. Hypermedia должна быть двигателем состояния приложения

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

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

5. Многоуровневая система

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

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

6. Код по требованию

Это необязательное ограничение и позволяет клиентам загружать программы для выполнения на стороне клиента. Лучший пример для этого — интерфейсные JavaScript-приложения. Это может показаться нам сейчас очень очевидным, но в раннем возрасте Интернета это была эволюционирующая концепция, и это полезная часть интернет-архитектуры.

Итак, как создать REST API?

Правильно использовать HTTP

Если вы строите RESTful API, используйте протокол RESTful. Для Интернета HTTP-протокол является определенным выбором. Создайте свой API, чтобы он правильно использовал HTTP.

Создайте единый интерфейс

Сопоставьте свои концепции с ресурсами и назначьте соответствующие идентификаторы для каждого из них. Простым примером может служить служба базы данных пользователей. В такой службе мы можем назвать два ресурса; Пользователей и пользователей (ресурс сбора). Эти ресурсы могут быть идентифицированы с URI / users и / user / {id} URI вашего интерфейса API.

Управляйте своим API-гиперссылками

Используйте ссылки для подключения ваших ресурсов. Это сделает ваш API доступным для клиентов, которые имеют очень мало первоначальных знаний о ваших ресурсах.

У вас нет прав для комментирования.

Как обеспечить безопасность REST API

Перевод статьи: Zbigniew Banach — How to Ensure REST API Security

WEB API приложений обеспечивают серверную часть для современных веб-приложений и мобильных приложений. Вызовы веб-API составляют более 80% всего веб-трафика, и киберпреступники все чаще ориентируются на API-интерфейсы, поэтому обеспечение безопасности веб-API имеет решающее значение. REST API — наиболее распространенный тип веб-API для веб-сервисов. Давайте посмотрим, что вы можете сделать, чтобы обеспечить безопасность REST API.

Что такое REST API?

REST (сокращение от REpresentational State Transfer) — это определенная архитектура программного обеспечения для веб-разработки, обычно используемая для HTTP-взаимодействия. RESTful API (или просто REST API) — это запросы от клиентского ПО к серверному ПО, которые следуют принципам REST, позволяя веб-клиентам и серверам взаимодействовать с огромным разнообразием веб-ресурсов. API REST используют стандартные методы HTTP (имена методов соответствуют определенным глаголам GET/POST/PUT/DELETE/HEAD) и коды состояния для обеспечения некоторого уровня стандартизации. Доступ к ним осуществляется через HTTP-URL и широко используются для веб-сервисов.

Примечание. API-интерфейсы REST не имеют состояния, как и сам протокол HTTP, что означает, что они не хранят никакой информации о текущих соединениях или сеансах (то есть каждый запрос не зависит от предыдущих). Веб-сервисы RESTful предоставляют способы доступа к ресурсам и управления ими, в то время как управление сеансом должно обрабатываться серверным приложением.

Два уровня безопасности REST API

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

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

Давайте посмотрим, как вы можете обеспечить безопасность REST API на этих двух уровнях. Подробное обсуждение рекомендаций по безопасности API см. OWASP REST Security Cheat Sheet.

Обеспечение безопасного доступа к API

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

Безопасность соединения

Безопасность начинается с самого соединения HTTP. API-интерфейсы Secure REST должны предоставлять только конечные точки HTTPS, чтобы гарантировать, что вся связь API-интерфейса шифруется с использованием SSL/TLS. Это позволяет клиентам аутентифицировать службу и защищает учетные данные API и передаваемые данные.

Контроль доступа к API

Многие веб-API доступны только для аутентифицированных пользователей, например, потому что они являются частными или требуют регистрации или оплаты. Поскольку REST API не имеют состояния, управление доступом осуществляется локальными конечными точками. Наиболее распространенные методы аутентификации REST API:

• Базовая аутентификация HTTP (HTTP Basic Authentication): учетные данные отправляются непосредственно в заголовках HTTP в кодировке Base64 без шифрования. Это самый простой метод аутентификации и самый простой в реализации. Он также наименее безопасный, поскольку конфиденциальные данные передаются в виде простого текста, поэтому его следует использовать только в сочетании с HTTPS.
• Веб-токены JSON (JSON Web Tokens — JWT): учетные данные и другие параметры доступа отправляются в виде структур данных JSON. Эти токены доступа могут быть подписаны криптографически и являются предпочтительным способом управления доступом к API REST. См. OWASP JWT Cheat для краткого обзора веб-токенов JSON и RFC 7519 для получения полной спецификации.
• OAuth: стандартные механизмы OAuth 2.0 могут использоваться для аутентификации и авторизации. OpenID Connect обеспечивает безопасную аутентификацию через OAuth 2.0. Например, API Google используют OAuth 2.0 для аутентификации и авторизации.

Авторизация пользователя с помощью ключей API

Ключи API предоставляют способ управления доступом к общедоступным службам REST. Операторы общедоступных веб-служб могут использовать ключи API для принудительного ограничения скорости вызовов API и уменьшение воздействия атак типа «отказ в обслуживании». Для монетизированных услуг организации могут использовать ключи API для предоставления доступа на основе приобретенного плана доступа.

Клиентские ограничения API

Чтобы минимизировать риски безопасности, операторы службы REST должны ограничивать подключение клиентов минимальными возможностями, необходимыми для службы. Это начинается с ограничения поддерживаемых методов HTTP, чтобы убедиться, что неправильно настроенные или злонамеренные клиенты не могут выполнять никаких действий, выходящих за пределы спецификации API и разрешенного уровня доступа. Например, если API разрешает только запросы GET, POST и другие типы запросов должны быть отклонены с кодом ответа 405 Method not allowed.

Защита приложений, которые предоставляют API

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

Конфиденциальные данные в API-интерфейсе

Вызовы API часто включают учетные данные, ключи API, токены сеансов и другую конфиденциальную информацию. Если эти данные включены непосредственно в URL-адреса, эти данные могут быть сохранены в журналах веб-сервера и могут быть украдены, если к журналам получать доступ злоумышленники. Чтобы избежать утечки конфиденциальной информации, веб-службы RESTful всегда должны отправлять ее в заголовках HTTP-запроса или в теле запроса (для запросов POST и PUT).

Проверка Content Type

Продолжая тему клиентских ограничений API, службы REST должны точно определять разрешенные типы контента (content type) и отклонять запросы, которые не имеют правильных объявлений в своих заголовках HTTP. Это означает тщательное указание разрешенных типов как в Content-Type, так и в заголовке Accept, а также в charset (где это возможно). Если служба включает JavaScript (или другой код сценария), она должна гарантировать, что тип содержимого в заголовке такой же, как в теле запроса, например application/javascript. Это помогает предотвратить атаки с использованием заголовков (header injection).

Заголовки безопасности в ответах (Response Security Headers)

Дополнительные заголовки безопасности HTTP security headers могут быть установлены для дальнейшего ограничения типа и объема запросов. К ним относятся X-Content-Type-Options: nosniff для предотвращения атак XSS (XSS attacks) на основе сниффинга MIME и X-Frame-Options: deny для предотвращения попыток clickjacking в старых браузерах.

Если служба не поддерживает междоменные вызовы (cross-domain), она должна отключить CORS (совместное использование ресурсов между источниками) в своих заголовках ответа. Если такие вызовы ожидаются, заголовки CORS должны точно указывать разрешенные источники.

Проверка входных данных

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

• Рассматривайте все параметры, объекты и другие входные данные как ненадежные.
• Используйте встроенные функции проверки, где это возможно.
• Проверьте размер запроса, длину и тип контента.
• Используйте строгую типизацию для параметров API (если поддерживается).
• Чтобы предотвратить SQL injection, избегайте создания запросов вручную — используйте вместо этого параметризованные запросы.
• Ведите белые списки разрешений (разрешено только то что указано в списке), везде где это возможно.
• Логгируйте все ошибки проверки ввода данных для обнаружения попыток ввода учетных данных.

Заключение

Веб-API являются основой современной веб-и мобильной разработки. Они позволяют приложениям и службам обмениваться данными и обмениваться данными между аппаратными и программными платформами. В то время как другие форматы API также все еще используются (например, SOAP), API-интерфейсы REST в настоящее время являются доминирующим типом, на которые приходится более 80% всех общедоступных веб-API. Они обеспечивают серверную часть для большинства мобильных приложений и устройств IoT и обеспечивают простую интеграцию между системами и приложениями.

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

Была ли вам полезна эта статья?

[15 / 3.1]

REST interface / API / For developers / SmsBliss

Передача сообщения
Проверка состояния отправленного сообщения (до 200 id в запросе)
Проверка очереди статусов отправленных сообщений
Проверка состояния счета
Список доступных подписей отправителя
Проверка активной версии API

Передача сообщения

GET запрос на сервер, вида

http://api.smsbliss.net/messages/v2/send/?phone=%2B71234567890&text=test

При успешной авторизации, в ответ сервис должен вернуть plain/text ответ вида

accepted;A132571BC

где до знака «;» сервис выдает ответ сервиса о статусе сообщения, а после знака «;» идентификатор сообщения (A-F 0-9, макс. 72 симв.)

Проверка состояния отправленного сообщения (до 200 id в запросе)

GET запрос на сервер, вида

http://api.smsbliss.net/messages/v2/status/?id=A132571BC&id=A132571BD&id=A132571BE

При успешной авторизации, в ответ сервис должен вернуть plain/text ответ вида

A132571BC;delivered
A132571BD;smsc submit
A132571BE;queued

где в каждой строке до запятой id запрашиваемого статуса, а после запятой ответ сервиса о статусе сообщения

Проверка очереди статусов отправленных сообщений

GET запрос на сервер, вида

http://api. smsbliss.net/messages/v2/statusQueue/?statusQueueName=myQueue1&limit=5

При успешной авторизации, в ответ сервис должен вернуть plain/text ответ вида

A132571BC;delivered
A132571BD;smsc submit
A132571BE;queued

где сервис возвращает по одному статусу в каждой строке (подробнее о статусах)

Проверка состояния счета

GET запрос на сервер, вида

http://api.smsbliss.net/messages/v2/balance/

При успешной авторизации, в ответ сервис должен вернуть plain/text ответ вида

RUB;540.15;0.0
SMS;589;100

где в каждой строке 1 значение – тип баланса, 2 значение – баланс, 3 значение – кредит (возможность использовать сервис при отрицательном балансе)

Список доступных подписей отправителя

GET запрос на сервер, вида

http://api.smsbliss.net/messages/v2/senders/

При успешной авторизации, в ответ сервис должен вернуть plain/text ответ вида

MyBrand;active;
3132018;pending;
MegaFon;blocked;bad sender name
TEST;default;

где в каждой строке 1 значение – имя подписи, 2 значение – статус, 3 значение – примечание

Проверка активной версии API

GET запрос

http://api. smsbliss.net/messages/v2/version/

При успешной авторизации, в ответ сервис должен вернуть plain/text ответ вида

2

где выводится номер активной версии API

Понимание REST | Spring по-русски!

REST (Representational State Transfer) был введен и определен в 2000 году Roy Fielding
в его докторской диссертации.
REST — это архитектурный стиль для проектирования распределенных систем. Он не является
стандартом, но определяет ограничения, такие как отсутствие состояний, клиент-серверная
взаимосвязь и унифицированный интерфейс. REST не связан строго с HTTP, но чаще всего
его ассоциируют именно с ним.

Принципы REST

• Ресурсы позволяют легко понять структуру каталогов URI
• Представления передают JSON или XML в качестве представления
  данных объекта и атрибутов
• Сообщения используют HTTP методы явно(например, GET, POST, PUT и DELETE)
• Отсутствие состояния взаимодействий не сохраняет контекст клиента
  на сервере между запросами

HTTP методы

Используются HTTP методы для определения CRUD (create, retrieve, update, delete) операций
HTTP запросов.

GET

Получение информации. GET запросы должны быть безопасны и
идемпотентны,
т.е. независимо от того, как много времени они повторяются с теми же самысыми параметрами,
результат останется тот же. Они могут иметь побочные эффекты, но пользователь не ожидает их,
поэтому они не могут критичными для функционирования системы. Запросы могут быть также
частичными или условными.

Получение адреса по ID, равным 1:

POST

Запрос что-то сделать с ресурсом по URI с предоставлением сущности. Часто POST используется
для создания новой сущности, но также возможно использовать и для обновления существующей.

Создание нового адреса:

PUT

Сохраняет сущность по URI. PUT может создавать новую сущноть или обновлять существующую.
PUT запрос идемпотентен. Идемпотентность — главное отличие в поведении между PUT и POST запросом.

Изменение адреса по ID, равным 1:

PUT заменяет сущетвующую сущность. Те элементы сущности, которые не представлены в запросе,
будут очищены или заменены на null.

PATCH

Обновляет только определенные поля сущности по URI. PATCH запрос идемпотентен.
Идемпотентность — главное отличие в поведении между PUT и POST запросом.

DELETE

Запрос, который удаляет ресурс; кроме того, ресурс не должен быть удален немедленно.
Он может быть асинхронным или «долгоиграющим» запросом.

Удаления адреса по ID, равным 1:

HTTP статус коды

Статус коды указывают на результат HTTP запроса.

• 1ХХ — информационный
• 2ХХ — успешное выполнение
• 3ХХ — перенаправление
• 4ХХ — ошибка клиента
• 5ХХ — ошибка сервера

Медиа типы

Accept и Content-Type HTTP заголовков могут быть использованы
для описания содержимого, которое будет отправлено или запрошено HTTP запросом. Клиент
может установить Accept в application/json, если он
запрашивает ответ в JSON. И наоборот, когда отправляются данные, установленный
Content-Type в application/xml говорит клиенту, что данные
были отправлены в XML форме.

С оригинальным текстом урока вы можете ознакомиться на
spring.io.

Please enable JavaScript to view the comments powered by Disqus.
comments powered by

Что такое REST API?

REST

REST — это набор архитектурных ограничений, а не протокол или стандарт. Разработчики API могут реализовать REST разными способами.

Когда клиентский запрос выполняется через RESTful API, он передает представление состояния ресурса запрашивающей стороне или конечной точке. Эта информация или представление доставляется в одном из нескольких форматов через HTTP: JSON (нотация объектов Javascript), HTML, XLT, Python, PHP или обычный текст. JSON является наиболее популярным языком программирования, потому что, несмотря на свое название, он не зависит от языка, а также читается как людьми, так и машинами.

Еще о чем следует помнить: заголовки и параметры также важны в методах HTTP HTTP-запроса RESTful API, поскольку они содержат важную информацию идентификатора в отношении метаданных запроса, авторизации, универсального идентификатора ресурса (URI), кэширования, файлов cookie. , и больше. Существуют заголовки запросов и ответов, каждый со своей собственной информацией о HTTP-соединении и кодами состояния.

Чтобы API считался RESTful, он должен соответствовать следующим критериям:

• Архитектура клиент-сервер, состоящая из клиентов, серверов и ресурсов, с запросами, управляемыми через HTTP.
• Связь клиент-сервер без сохранения состояния, что означает, что информация о клиенте не сохраняется между запросами на получение, и каждый запрос является отдельным и несвязанным.
• Кэшируемые данные, упрощающие взаимодействие клиент-сервер.
• Единый интерфейс между компонентами, так что информация передается в стандартной форме. Для этого необходимо, чтобы:
  • Запрошенные ресурсы идентифицируемы и отделены от представлений, отправленных клиенту.
  • Ресурсы могут управляться клиентом через представление, которое они получают, потому что представление содержит достаточно информации для этого.
  • Самоописательные сообщения, возвращаемые клиенту, содержат достаточно информации, чтобы описать, как клиент должен их обработать.
  • доступен гипертекст / гипермедиа, что означает, что после доступа к ресурсу клиент должен иметь возможность использовать гиперссылки для поиска всех других доступных в настоящее время действий, которые он может предпринять.
• Многоуровневая система, которая организует серверы каждого типа (отвечающие за безопасность, балансировку нагрузки и т. Д.), Включала извлечение запрошенной информации в иерархии, невидимые для клиента.
• Код по запросу (необязательно): возможность отправлять исполняемый код с сервера клиенту по запросу, расширяя функциональность клиента.

Хотя REST API соответствует этим критериям, он по-прежнему считается более простым в использовании, чем предписанный протокол, такой как SOAP (Simple Object Access Protocol), который имеет особые требования, такие как обмен сообщениями XML, а также встроенные средства безопасности и соответствия транзакциям. что делает его медленнее и тяжелее.

Напротив, REST — это набор руководящих принципов, которые можно реализовать по мере необходимости, делая REST API более быстрыми и легкими, с повышенной масштабируемостью — идеально подходящими для Интернета вещей (IoT) и разработки мобильных приложений.

REST и SOAP

REST и SOAP — это два разных подхода к передаче данных в режиме онлайн. В частности, оба определяют, как создавать интерфейсы прикладного программирования (API), которые позволяют передавать данные между веб-приложениями. Передача репрезентативного состояния (REST) ​​- это набор архитектурных принципов. Протокол простого доступа к объектам (SOAP) — это официальный протокол, поддерживаемый Консорциумом Всемирной паутины (W3C). Основное отличие состоит в том, что SOAP — это протокол, а REST — нет. Как правило, API будет придерживаться REST или SOAP, в зависимости от варианта использования и предпочтений разработчика.

Загрузите руководство пользователя нашего API.

REST: передача репрезентативного состояния

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

Когда запрос данных отправляется в REST API, это обычно выполняется через протокол передачи гипертекста (обычно называемый HTTP).После получения запроса API-интерфейсы, разработанные для REST (называемые RESTful API или веб-службы RESTful), могут возвращать сообщения в различных форматах: HTML, XML, простой текст и JSON. JSON (объектная нотация JavaScript) является предпочтительным форматом сообщений, поскольку его можно прочитать на любом языке программирования (несмотря на название), он удобочитаем для людей и машин и имеет небольшой вес. Таким образом, RESTful API становятся более гибкими и их проще настраивать.

Приложение называется RESTful, если оно следует 6 руководящим принципам архитектуры.Приложение RESTful должно иметь:

1. Архитектура клиент-сервер, состоящая из клиентов, серверов и ресурсов.
2. Связь клиент-сервер без сохранения состояния, то есть между запросами на сервере не хранится клиентский контент. Информация о состоянии сеанса вместо этого передается клиенту.
3. Кэшируемые данные для устранения необходимости некоторых взаимодействий клиент-сервер.
4. Единый интерфейс между компонентами, так что информация передается в стандартизированной форме, а не в зависимости от потребностей приложения.Рой Филдинг, создатель REST, описывает это как «центральную особенность, которая отличает архитектурный стиль REST от других сетевых стилей».
5. Ограничение многоуровневой системы, где взаимодействие клиент-сервер может осуществляться через иерархические уровни.
6. Код по запросу, позволяющий серверам расширять функциональность клиента путем передачи исполняемого кода (хотя также снижает видимость, что делает это необязательным руководством).

SOAP: простой протокол доступа к объектам

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

Общие спецификации веб-сервисов включают:

• Безопасность веб-сервисов (WS-security) : стандартизирует способы защиты и передачи сообщений с помощью уникальных идентификаторов, называемых токенами.
• WS-ReliableMessaging : стандартизирует обработку ошибок между сообщениями, передаваемыми через ненадежную ИТ-инфраструктуру.
• Адресация веб-сервисов (WS-адресация) : Пакеты маршрутизации информации в виде метаданных в заголовках SOAP, вместо того, чтобы хранить такую ​​информацию глубже в сети.
• Язык описания веб-служб (WSDL) : описывает, что делает веб-служба, а также где эта служба начинается и заканчивается.

Когда запрос данных отправляется в SOAP API, он может быть обработан через любой из протоколов прикладного уровня: HTTP (для веб-браузеров), SMTP (для электронной почты), TCP и другие.Однако, как только запрос получен, возвращаемые сообщения SOAP должны быть возвращены в виде XML-документов — языка разметки, который может быть как человеком, так и машиночитаемым. Завершенный запрос к SOAP API не кэшируется браузером, поэтому он не может быть доступен позже без повторной отправки в API.

SOAP против REST

Многие унаследованные системы могут по-прежнему придерживаться SOAP, тогда как REST появился позже и часто рассматривается как более быстрая альтернатива в веб-сценариях. REST — это набор руководящих принципов, которые предлагают гибкую реализацию, тогда как SOAP — это протокол с особыми требованиями, такими как обмен сообщениями XML.

API-интерфейсы REST легковесны, что делает их идеальными для новых контекстов, таких как Интернет вещей (IoT), разработка мобильных приложений и бессерверные вычисления. Веб-службы SOAP предлагают встроенные средства безопасности и соответствия транзакциям, которые соответствуют многим потребностям предприятия, но это также усложняет их выполнение. Кроме того, многие общедоступные API, такие как Google Maps API, следуют рекомендациям REST.

Почему Red Hat?

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

Что такое API?

API — это набор определений и протоколов для создания и интеграции прикладного программного обеспечения. API означает интерфейс прикладного программирования.

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

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

Поскольку API-интерфейсы упрощают интеграцию компонентов новых приложений в существующую архитектуру, они помогают бизнесу и ИТ-командам сотрудничать. Потребности бизнеса часто быстро меняются в ответ на постоянно меняющиеся цифровые рынки, где новые конкуренты могут изменить целую отрасль с помощью нового приложения.Чтобы оставаться конкурентоспособными, важно поддерживать быстрое развитие и внедрение инновационных услуг. Разработка облачных приложений — это очевидный способ увеличить скорость разработки, и она основана на подключении архитектуры приложений микросервисов через API.

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

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

В качестве альтернативы распространитель книг может предоставить API для проверки наличия на складе. У этого подхода есть несколько преимуществ:

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

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

Существует три подхода к политикам выпуска API.

Частный

API предназначен только для внутреннего использования.Это дает компаниям максимальный контроль над своим API.

Партнер

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

Public

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

Инновации с помощью API

Представление ваших API партнерам или общественности может:

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

Отлично звучит, правда? Но как API могут все это сделать?

Вернемся к примеру с компанией по распространению книг.

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

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

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

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

Чрезвычайно краткая история API-интерфейсов

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

Удаленные API-интерфейсы

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

Веб-API обычно используют HTTP для сообщений запроса и предоставляют определение структуры сообщений ответа.Эти ответные сообщения обычно имеют форму файла XML или JSON. И XML, и JSON являются предпочтительными форматами, поскольку они представляют данные таким образом, чтобы другие приложения могли легко ими манипулировать.

Что было сделано для улучшения API?

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

Немного SOAP, много REST

По мере распространения веб-API была разработана спецификация протокола, помогающая стандартизировать обмен информацией: Простой протокол доступа к объектам, более известный как SOAP.API-интерфейсы, разработанные с помощью SOAP, используют XML для своего формата сообщений и получают запросы через HTTP или SMTP. SOAP упрощает обмен информацией для приложений, работающих в разных средах или написанных на разных языках.

Другая спецификация — передача репрезентативного состояния (REST). Веб-API, которые придерживаются архитектурных ограничений REST, называются RESTful API. REST принципиально отличается от SOAP: SOAP — это протокол, а REST — это архитектурный стиль. Это означает, что официального стандарта для веб-API RESTful не существует.Как определено в диссертации Роя Филдинга «Архитектурные стили и проектирование сетевых архитектур программного обеспечения», API-интерфейсы являются RESTful, если они соответствуют 6 руководящим ограничениям системы RESTful:

• Архитектура клиент-сервер: REST Архитектура состоит из клиентов, серверов и ресурсов и обрабатывает запросы через HTTP.

• Без сохранения состояния: Клиентское содержимое не сохраняется на сервере между запросами.Информация о состоянии сеанса вместо этого хранится у клиента.

• Кэшируемость: Кэширование может устранить необходимость в некоторых взаимодействиях клиент-сервер.

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

• Код по запросу (необязательно): Серверы могут расширять функциональность клиента, передавая исполняемый код.

• Единый интерфейс: Это ограничение является ядром дизайна RESTful API и включает в себя 4 аспекта:

  • Идентификация ресурсов в запросах: Ресурсы идентифицируются в запросах и отделены от представлений, возвращаемых клиенту .

  • Управление ресурсами посредством представлений: Клиенты получают файлы, представляющие ресурсы. Эти представления должны содержать достаточно информации, чтобы разрешить изменение или удаление.

  • Самоописательные сообщения: Каждое сообщение, возвращаемое клиенту, содержит достаточно информации, чтобы описать, как клиент должен обрабатывать информацию.

  • Гипермедиа как движок состояния приложения: После доступа к ресурсу клиент REST должен иметь возможность обнаруживать через гиперссылки все другие действия, доступные в данный момент.

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

В последние годы спецификация OpenAPI стала общепринятым стандартом для определения REST API. OpenAPI предоставляет разработчикам независимый от языка способ создания интерфейсов REST API, чтобы пользователи могли понять их с минимальными догадками.

Еще один стандарт API, который должен появиться, — это GraphQL, язык запросов и среда выполнения на стороне сервера, являющаяся альтернативой REST. GraphQL отдает приоритет предоставлению клиентам именно тех данных, которые они запрашивают, и не более того.В качестве альтернативы REST GraphQL позволяет разработчикам создавать запросы, которые извлекают данные из нескольких источников данных за один вызов API.

Сравнение архитектуры SOA и микросервисов

Два архитектурных подхода, в которых больше всего используются удаленные API, — это сервис-ориентированная архитектура (SOA) и архитектура микросервисов. SOA, самый старый из двух подходов, начинался как улучшение монолитных приложений. В то время как одно монолитное приложение делает все, некоторые функции могут предоставляться разными приложениями, которые слабо связаны через шаблон интеграции, например, служебная шина предприятия (ESB).

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

Архитектура микросервисов похожа на шаблоны SOA в том, что они используют специализированные, слабосвязанные службы. Но они пошли еще дальше в разрушении традиционных архитектур. Службы в архитектуре микросервисов используют общую структуру обмена сообщениями, такую ​​как RESTful API.Они используют RESTful API для связи друг с другом без сложных транзакций преобразования данных или дополнительных уровней интеграции. Использование RESTful API позволяет и даже поощряет более быструю доставку новых функций и обновлений. Каждая услуга индивидуальна. Одна служба может быть заменена, улучшена или удалена, не затрагивая другие службы в архитектуре. Эта облегченная архитектура помогает оптимизировать распределенные или облачные ресурсы и поддерживает динамическую масштабируемость для отдельных сервисов.

Stateful vs stateless

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

Без сохранения состояния

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

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

Stateful

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

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

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

Контейнеры и состояние

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

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

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

Управление контейнерами без сохранения состояния и с отслеживанием состояния

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

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

Stateful, Stateless и Red Hat

Когда дело доходит до stateful или stateless, Red Hat поможет вам.Независимо от того, организуете ли вы контейнеры с отслеживанием состояния на нашей корпоративной платформе Kubernetes, Red Hat OpenShift или создаете унифицированную среду для разработки приложений с помощью интеграции Red Hat, вы получите поддержку нашей отмеченной наградами поддержки и крупнейшей в отрасли экосистемы партнеров. .

Посмотрите, как все наши продукты создают решения, повышают продуктивность разработчиков и продвигают инновации — с открытым исходным кодом.

Понимание и использование API-интерфейсов REST — Smashing Magazine

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

Есть большая вероятность, что вы встретили термин «REST API», если задумывались о получении данных из другого источника в Интернете, например Twitter или Github. Но что такое REST API? Что это может для вас сделать? Как ты это используешь?

В этой статье вы узнаете все, что вам нужно знать об API REST, чтобы иметь возможность читать документацию по API и эффективно их использовать.

Часть: Rest API и GraphQL

Что такое REST API

Допустим, вы пытаетесь найти видео о Бэтмене на Youtube.Вы открываете Youtube, набираете «Бэтмен» в поле поиска, нажимаете Enter и видите список видео о Бэтмене. Аналогичным образом работает REST API. Вы что-то ищете и получаете список результатов от службы, из которой запрашиваете.

API — это интерфейс прикладного программирования. Это набор правил, которые позволяют программам общаться друг с другом. Разработчик создает API на сервере и позволяет клиенту общаться с ним.

REST определяет, как выглядит API.Это расшифровывается как «Передача состояния представительства». Это набор правил, которым следуют разработчики при создании своего API. Одно из этих правил гласит, что вы должны иметь возможность получать фрагмент данных (называемый ресурсом), когда вы ссылаетесь на определенный URL-адрес.

Каждый URL-адрес называется запросом , а данные, отправленные вам обратно, называются ответом .

Анатомия запроса

Важно знать, что запрос состоит из четырех частей:

1. Конечная точка
2. Метод
3. Заголовки
4. Данные (или тело)

Конечная точка (или маршрут) — это URL-адрес, который вы запрашиваете.Это следующая структура:

  root-endpoint /?  

Корневая конечная точка — это начальная точка API, из которого вы запрашиваете. Конечная корневая точка API Github — https://api.github.com , а API Твиттера — https://api.twitter.com .

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

Вы можете получить доступ к путям так же, как вы можете ссылаться на части веб-сайта. Например, чтобы получить список всех сообщений с тегами «JavaScript» в Smashing Magazine, перейдите по адресу https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ — это корневая конечная точка, а / tag / javascript — это путь.

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

  / users /: username / repos
  

Любые двоеточия (: ) на пути обозначают переменную. Вы должны заменить эти значения фактическими значениями, когда вы отправляете свой запрос. В этом случае вам следует заменить : username фактическим именем пользователя, которого вы ищете. Если я ищу свою учетную запись Github, я заменяю : имя пользователя на zellwk .

Конечная точка для получения списка моих репозиториев на Github:

  https: // api.github.com/users/zellwk/repos  

Последняя часть конечной точки — это параметров запроса . Технически параметры запроса не являются частью архитектуры REST, но вы увидите, что многие API используют их. Итак, чтобы помочь вам полностью понять, как читать и использовать API, мы также поговорим о них.
Параметры запроса дают вам возможность изменить ваш запрос парами «ключ-значение». Они всегда начинаются с вопросительного знака (? ). Каждая пара параметров затем разделяется амперсандом ( и ), например:

 ? Query1 = value1 & query2 = value2.
  

Когда вы пытаетесь получить список пользовательских репозиториев на Github, вы добавляете в свой запрос три возможных параметра для изменения предоставленных вам результатов:

Github позволяет вам добавить три параметра в ваш запрос

Если вы хотите получить список репозиториев, которые я недавно отправил, вы можете установить sort на push .

  https://api.github.com/users/zellwk/repos?sort=pushing
  

Как узнать, работает ли эта конечная точка? Что ж, пора попробовать!

Тестирование конечных точек с помощью curl

Вы можете отправить запрос на любом языке программирования. Пользователи JavaScript могут использовать такие методы, как Fetch API и метод JQuery Ajax; Пользователи Ruby могут использовать класс Ruby Net :: HTTP, пользователи Python могут использовать запросы Python; и так далее.

В этой статье мы будем использовать утилиту командной строки cURL.Мы используем cURL, потому что документация API обычно пишется со ссылкой на cURL. Если вы понимаете, как использовать cURL, у вас не будет проблем с пониманием документации API. Затем вы можете легко выполнять запросы на предпочитаемом вами языке.

Прежде чем продолжить, убедитесь, что на вашем компьютере установлен cURL. Откройте свой терминал и введите curl -version . Эта команда проверяет версию cURL, установленную в вашей системе.

  curl - версия
  

Если у вас не установлен cURL, вы получите ошибку «команда не найдена».Если вы получили эту ошибку, вам нужно будет установить curl, прежде чем двигаться дальше.

Чтобы использовать cURL, введите curl , а затем конечную точку, которую вы запрашиваете. Например, чтобы получить корневую конечную точку Github, введите следующее:

  curl https://api.github.com
  

После того, как вы нажмете Enter, вы должны получить ответ от Github, который выглядит следующим образом:

Ответ от корневой конечной точки Github

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

  curl https://api.github.com/users/zellwk/repos  

Если вы хотите включить параметры запроса с cURL, убедитесь, что вы добавили обратная косая черта ( \ ) перед ? и = символов. Это потому что ? и = — специальные символы в командной строке. Вам нужно использовать перед ними \ , чтобы командная строка интерпретировала их как обычные символы:

  curl https: // api.github.com/users/zellwk/repos\?sort\=pressed
  

Попробуйте использовать любую из команд и выполните запрос! Вы получите ответ, аналогичный тому, что вы видели, с root-endpont Github (но с гораздо большим количеством данных).

JSON

JSON (нотация объектов JavaScript) общий формат для отправки и запроса данных через REST API. Ответ, который Github отправляет вам, также имеет формат JSON.

Объект JSON выглядит как объект JavaScript. В JSON каждое свойство и значение должны быть заключены в двойные кавычки, например:

  {
  "свойство1": "значение1",
  "свойство2": "значение2",
  "свойство3": "значение3"
}
  

Назад к анатомии запроса

Вы узнали, что запрос состоит из четырех частей.

1. Конечная точка
2. Метод
3. Заголовки
4. Данные (или тело)

Давайте рассмотрим остальную часть того, что составляет запрос.

Метод

Метод — это тип запроса, который вы отправляете на сервер. Вы можете выбрать один из следующих пяти типов ниже:

Эти методы придают смысл отправляемому вами запросу. Они используются для выполнения четырех возможных действий: Создать , Прочитать , Обновить и Удалить (CRUD).

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

Запрос GET требуется для получения списка репозиториев от пользователя

Запрос GET требуется для получения списка репозиториев от пользователя .Для создания нового репозитория Github вам потребуется запрос POST :

Запрос POST требуется для создания нового репозитория

Вы можете установить метод запроса в cURL, написав -X или --request , а затем метод запроса. Эта команда ниже пытается создать репозиторий через cURL:

  curl -X POST https://api.github.com/user/repos
  

Попробуйте выполнить этот запрос. Вы получите ответ о том, что требуется аутентификация.(Подробнее об аутентификации позже).

  {
  "message": "Требуется аутентификация",
  "documentation_url": "https://developer.github.com/v3"
}
  

Заголовки

Заголовки используются для предоставления информации как клиенту, так и серверу. Его можно использовать для многих целей, таких как аутентификация и предоставление информации о содержимом тела. Вы можете найти список допустимых заголовков в Справочнике по HTTP-заголовкам MDN.

HTTP-заголовки — это пары «свойство-значение», разделенные двоеточием.В приведенном ниже примере показан заголовок, который сообщает серверу ожидать содержимого JSON.

  «Content-Type: application / json». Отсутствует открытие ».
  

Вы можете отправлять заголовки HTTP с помощью curl с помощью параметра -H или --header . Чтобы отправить указанный выше заголовок в API Github, используйте эту команду:

  curl -H "Content-Type: application / json" https://api.github.com  

(Примечание: заголовок Content-Type не является обязательным требованием для работы API Github.Это только пример, чтобы проиллюстрировать, как использовать заголовок с cURL).

Для просмотра отправленных заголовков можно использовать параметр -v или --verbose при отправке запроса, например:

  curl -H "Content-Type: application / json" https : //api.github.com -v
  

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

Здесь * относится к дополнительной информации, предоставляемой cURL. > относится к заголовкам запросов, а < относится к заголовкам ответов.

Данные (или «тело»)

Данные (иногда называемые «телом» или «сообщением») содержат информацию, которую вы хотите отправить на сервер. Эта опция используется только с запросами POST , PUT , PATCH или DELETE .

Для отправки данных через cURL вы можете использовать параметр -d или --data :

  curl -X POST  -d property1 = value1
  

Чтобы отправить несколько полей данных, вы можете создать несколько опций -d :

  curl -X POST  -d property1 = value1 -d property2 = value2
  

Если это имеет смысл, вы можете разбить свой запрос на несколько строк \ , чтобы его было легче читать:

  curl -X POST  \
  -d свойство1 = значение1 \
  -d свойство2 = значение2
  

Если вы знаете, как раскрутить сервер, вы можете создать API и протестировать свои собственные данные.Если вы не знаете, но чувствуете себя достаточно смелым, чтобы попробовать, вы можете изучить эту статью, чтобы научиться создавать сервер с помощью Node, Express и MongoDB

Если вы не хотите раскручивать свой сервер, вы можете перейти на Requestbin.com ( это бесплатно! ) и нажмите «создать конечную точку». Вам будет предоставлен URL-адрес, который можно использовать для тестирования запросов, например https://requestb.in/1ix963n1 , показанный на рисунке ниже.

Корзина запросов дает вам уникальный URL-адрес, который можно использовать в течение 48 часов.

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

Теперь попробуйте отправить данные в корзину запросов, а затем обновите веб-страницу своей корзины. Вы увидите некоторые данные, например:

  curl -X POST https://requestb.in/1ix963n1 \
  -d свойство1 = значение1 \
  -d свойство2 = значение2
  

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

По умолчанию cURL отправляет данные так, как если бы они отправлялись через «поля формы» на странице.Если вы хотите отправить данные JSON, вам нужно установить Content-Type на application / json , и вам нужно будет отформатировать ваши данные как объект JSON, например:

  curl -X ЗАПИСЬ https://requestb.in/1ix963n1 \
  -H "Content-Type: application / json" \
  -d '{
  "свойство1": "значение1",
  "свойство2": "значение2"
} '
  

Отправка данных в формате JSON

И это (почти!) Все, что вам нужно знать о структуре запроса.

Теперь, помните, когда вы пытались отправить запрос POST через API Github, вы получили сообщение «Требуется аутентификация»? Это потому, что у вас нет прав на выполнение запроса POST !

Аутентификация

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

Поскольку запросы POST , PUT , PATCH и DELETE изменяют базу данных, разработчики почти всегда помещают их за стеной аутентификации. В некоторых случаях запрос GET также требует аутентификации (например, когда вы входите в свой банковский счет для проверки текущего баланса).

В Интернете есть два основных способа аутентификации:

1. С помощью имени пользователя и пароля (также называемого базовой аутентификацией)
2. С секретным токеном

Метод секретного токена включает oAuth, который позволяет вам аутентифицироваться в социальных сетях, таких как Github, Google, Twitter, Facebook и т. д.

В этой статье вы научитесь использовать только базовую аутентификацию с помощью имени пользователя и пароля. Если вы заинтересованы в аутентификации с помощью oAuth, я предлагаю прочитать Зак Гроссбарт «Что нужно знать о OAuth3 и входе в систему с помощью Facebook».

Чтобы выполнить базовую аутентификацию с помощью cURL, вы можете использовать опцию -u , за которой следует ваше имя пользователя и пароль, например:

  curl -x POST -u "username: password" https: // api. github.com/user/repos
  

Попробуйте аутентифицироваться со своим именем пользователя и паролем в приведенном выше запросе.После успешной аутентификации вы увидите, что ответ изменится с «Требуется аутентификация» на «Проблемы с анализом JSON».

Это связано с тем, что вы еще не предоставили серверу какие-либо данные (которые требуются для всех запросов POST , PUT , PATCH и DELETE ).

С уже полученными знаниями вы сможете отредактировать приведенный выше код для создания репозитория Github через ваш cURL. Я бы позволил вам попробовать самому!

Теперь поговорим о кодах состояния HTTP и сообщениях об ошибках.

Коды состояния и сообщения об ошибках HTTP

Некоторые из сообщений, полученных вами ранее, например «Требуется аутентификация» и «Проблемы с анализом JSON», являются сообщениями об ошибках. Они появляются только тогда, когда с вашим запросом что-то не так.
Коды состояния HTTP позволяют быстро определить статус ответа. Диапазон от 100+ до 500+. Как правило, числа соответствуют следующим правилам:

1. 200+ означает, что запрос преуспел, .
2. 300+ означает, что запрос перенаправлен на другой URL-адрес
3. 400+ означает, что произошла ошибка , исходящая от клиента произошла
4. 500+ означает ошибку , исходящую от сервера произошло

Состояние ответа можно отладить с помощью параметра подробного вывода ( -v или --verbose ) или параметра заголовка ( -I или --head ).

Например, если вы попытались добавить -I в запрос POST без указания имени пользователя и пароля, вы получите код состояния 401 (Неавторизованный):

Пример неавторизованного запроса

Если ваш запрос недействителен поскольку ваши данные неверны или отсутствуют, вы обычно получаете код статуса 400 (неверный запрос).

Пример неверного запроса

Чтобы получить дополнительную информацию о конкретных кодах состояния HTTP, вы можете обратиться к справочнику по состоянию HTTP MDN.

Версии API

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

Вы можете запросить конкретную версию API двумя способами. Какой способ вы выберете, зависит от того, как написан API.

Эти два способа:

1. Непосредственно в конечной точке
2. В заголовке запроса

Twitter, например, использует первый метод.На момент написания API Twitter был версии 1.1, о чем свидетельствует его конечная точка:

  https://api.twitter.com/1.1/account/settings.json.
  

Github, напротив, использует второй метод. На момент написания API Github имеет версию 3, и вы можете указать версию с заголовком Accept :

  curl https://api.github.com -H Accept: application / vnd.github.v3 + json
  

Завершение

В этой статье вы узнали, что такое REST API и как использовать cURL для выполнения запроса с помощью методов GET , POST , PUT , PATCH и DELETE .Кроме того, вы также узнали, как аутентифицировать свои запросы с помощью параметра -u и что означают статусы HTTP.

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

(rb, ra, il)

Что такое REST

REST - это аббревиатура от RE презентационного S tate T ransfer.Это архитектурный стиль для распределенных гипермедийных систем , впервые представленный Роем Филдингом в 2000 году в его знаменитой диссертации.

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

Руководящие принципы REST

1. Клиент-сервер - отделяя проблемы пользовательского интерфейса от проблем хранения данных, мы улучшаем переносимость пользовательского интерфейса на нескольких платформах и улучшаем масштабируемость за счет упрощения серверных компонентов.
2. Без сохранения состояния - Каждый запрос от клиента к серверу должен содержать всю информацию, необходимую для понимания запроса, и не может использовать преимущества какого-либо сохраненного контекста на сервере. Таким образом, состояние сеанса полностью зависит от клиента.
3. Cacheable - Ограничения кеширования требуют, чтобы данные в ответе на запрос были явно или неявно помечены как кэшируемые или некэшируемые. Если ответ кэшируется, то кэш клиента получает право повторно использовать эти данные ответа для последующих эквивалентных запросов.
4. Единый интерфейс - За счет применения принципа универсальности программной инженерии к компонентному интерфейсу упрощается общая архитектура системы и улучшается видимость взаимодействий. Чтобы получить единообразный интерфейс, необходимо несколько архитектурных ограничений, определяющих поведение компонентов. REST определяется четырьмя ограничениями интерфейса: идентификация ресурсов; манипулирование ресурсами через представления; информативные сообщения; и гипермедиа как двигатель состояния приложения.
5. Многоуровневая система - Стиль многоуровневой системы позволяет составлять архитектуру из иерархических уровней, ограничивая поведение компонентов таким образом, чтобы каждый компонент не мог «видеть» за пределами непосредственного уровня, с которым они взаимодействуют.
6. Код по запросу (необязательно) - REST позволяет расширять функциональность клиента путем загрузки и выполнения кода в форме апплетов или сценариев. Это упрощает работу с клиентами за счет сокращения количества функций, требуемых для предварительной реализации.

Ресурс

Ключевой абстракцией информации в REST является ресурс . Любая информация, которая может быть названа, может быть ресурсом: документом или изображением, временной службой, набором других ресурсов, невиртуальным объектом (например, человеком) и т. Д. REST использует идентификатор ресурса для идентификации конкретного ресурса, участвующего во взаимодействии между компонентами.

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

Формат данных представления известен как тип носителя . Тип мультимедиа определяет спецификацию, которая определяет, как должно обрабатываться представление. Настоящий RESTful API выглядит как гипертекст . Каждая адресуемая единица информации содержит адрес либо явно (например,g., ссылка и атрибуты id) или неявно (например, полученный из определения типа мультимедиа и структуры представления).

Согласно Рою Филдингу:

Гипертекст (или гипермедиа) означает одновременное представление информации и элементы управления , так что информация становится аффордансом, с помощью которого пользователь (или автомат) получает выбор и выбирает действия. Помните, что гипертекст не обязательно должен быть HTML (или XML, или JSON) в браузере. Машины могут переходить по ссылкам, когда они понимают формат данных и типы отношений.

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

Каждый тип носителя определяет модель обработки по умолчанию. Например, HTML определяет процесс визуализации гипертекста и поведение браузера вокруг каждого элемента.Это не имеет никакого отношения к ресурсным методам GET / PUT / POST / DELETE /…, кроме того факта, что некоторые элементы медиа-типа будут определять модель процесса, которая выглядит как «якорные элементы с атрибутом href создают гипертекстовую ссылку, которая при выборе вызывает поисковый запрос (GET) для URI, соответствующего атрибуту href в кодировке CDATA ».

Методы ресурсов

Еще одна важная вещь, связанная с REST, - это методов ресурсов , которые будут использоваться для выполнения желаемого перехода.Многие люди ошибочно связывают методы ресурсов с методами HTTP GET / PUT / POST / DELETE .

Рой Филдинг никогда не упоминал никаких рекомендаций относительно того, какой метод использовать в каких условиях. Все, что он подчеркивает, это то, что это должен быть единый интерфейс . Если вы решили, что для обновления ресурса будет использоваться HTTP POST - а не большинство людей рекомендуют HTTP PUT - все в порядке, и интерфейс приложения будет RESTful.

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

REST API следует вводить без каких-либо предварительных знаний, кроме начального URI (закладки) и набора стандартизованных типов мультимедиа, которые подходят для целевой аудитории (т. Е. Должны быть поняты любым клиентом, который может использовать API). С этого момента все переходы между состояниями приложения должны управляться выбором клиентом предоставленных сервером вариантов, которые присутствуют в полученных представлениях или подразумеваются манипуляциями пользователя с этими представлениями. Переходы могут определяться (или ограничиваться) знанием клиента о типах мультимедиа и механизмах связи ресурсов, и то и другое может быть улучшено на лету (например,г., код по запросу).
[Отказ здесь означает, что внешняя информация управляет взаимодействием, а не гипертекстом.]

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

REST и HTTP - это не одно и то же !!

Многие люди предпочитают сравнивать HTTP с REST. REST и HTTP - это не одно и то же.

REST! ​​= HTTP

Хотя, поскольку REST также намеревается сделать Интернет (Интернет) более упорядоченным и стандартным, он выступает за более строгое использование принципов REST. И именно здесь люди пытаются начать сравнивать REST с Интернетом (HTTP). Рой Филдинг в своей диссертации нигде не упоминал директивы реализации, включая любые предпочтения протокола и HTTP. Пока вы соблюдаете 6 руководящих принципов REST, вы можете называть свой интерфейс RESTful.

Проще говоря, в архитектурном стиле REST данные и функции считаются ресурсами, и доступ к ним осуществляется с помощью унифицированных идентификаторов ресурсов (URI). Ресурсы обрабатываются с помощью набора простых, четко определенных операций. Клиенты и серверы обмениваются представлениями ресурсов с помощью стандартизованного интерфейса и протокола - обычно HTTP.

Ресурсы отделены от своего представления, поэтому к их содержимому можно получить доступ в различных форматах, таких как HTML, XML, обычный текст, PDF, JPEG, JSON и другие.Метаданные о ресурсе доступны и используются, например, для управления кэшированием, обнаружения ошибок передачи, согласования соответствующего формата представления и выполнения аутентификации или управления доступом. И что наиболее важно, каждое взаимодействие с ресурсом не имеет состояния.

Все эти принципы помогают приложениям RESTful быть простыми, легкими и быстрыми.

Ссылки:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
http: //www.ics.uci.edu/~fielding/pubs/dissis/rest_arch_style.htm

Была ли эта статья полезной?

Принципы и архитектурные ограничения REST

REST означает Re презентационный S tate T ransfer, термин, придуманный Роем Филдингом в 2000 году. Это архитектурный стиль для разработки слабо связанных приложений через HTTP. это часто используется при разработке веб-сервисов. REST не применяет никаких правил относительно того, как это должно быть реализовано на более низком уровне, он просто устанавливает руководящие принципы проектирования высокого уровня и оставляет вас думать о своей собственной реализации.

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

Давайте начнем со стандартного дизайна, чтобы понять, что Рой Филдинг хочет, чтобы мы построили. Затем мы обсудим мои мысли, которые будут больше касаться более тонких моментов, пока вы разрабатываете свои RESTful API.

Архитектурные ограничения

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

1. Единый интерфейс
2. Клиент-сервер
3. Без сохранения состояния
4. Кэшируемая
5. Многоуровневая система
6. Код по запросу (необязательно)

Единый интерфейс

Поскольку применяется само имя ограничения, вы ДОЛЖНЫ выбрать интерфейс API для ресурсов внутри системы, которые доступны потребителям API и неукоснительно им следуют.Ресурс в системе должен иметь только один логический URI, который должен обеспечивать способ получения связанных или дополнительных данных. Всегда лучше синонимизировать ресурс с веб-страницей .

Любой отдельный ресурс не должен быть слишком большим и содержать все и вся в своем представлении. В соответствующих случаях ресурс должен содержать ссылок (HATEOAS), указывающих на относительные URI для получения связанной информации.

Кроме того, представления ресурсов в системе должны соответствовать определенным правилам, таким как соглашения об именах, форматы ссылок или формат данных (XML или / и JSON).

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

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

Клиент-сервер

Это ограничение по существу означает, что клиентское приложение и серверное приложение ДОЛЖНЫ иметь возможность развиваться отдельно, без какой-либо зависимости друг от друга. Клиент должен знать только URI ресурсов, и все.Сегодня это стандартная практика в веб-разработке, поэтому с вашей стороны ничего особенного не требуется. Будь проще.

Серверы и клиенты также могут быть заменены и разработаны независимо, если интерфейс между ними не изменен.

Stateless

Рой Филдинг черпал вдохновение из HTTP, поэтому он отражается в этом ограничении. Сделайте все взаимодействия клиент-сервер без сохранения состояния. Сервер не будет хранить ничего о последнем HTTP-запросе, сделанном клиентом. Он будет рассматривать каждый запрос как новый.Ни сеанса, ни истории.

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

Контекст клиента не должен храниться на сервере между запросами. Клиент отвечает за управление состоянием приложения.

Cacheable

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

В REST кэширование должно применяться к ресурсам, когда это применимо, и затем эти ресурсы ДОЛЖНЫ объявить себя кэшируемыми. Кэширование может быть реализовано на сервере или на стороне клиента.

Хорошо управляемое кэширование частично или полностью исключает некоторые взаимодействия клиент-сервер, дополнительно улучшая масштабируемость и производительность.

Многоуровневая система

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

Код по запросу (необязательно)

Ну, это ограничение необязательно.