Добро пожаловать в форум, Guest  >>   Войти | Регистрация | Поиск | Правила | В избранное | Подписаться
Все форумы / Разработка информационных систем Новый топик    Ответить
Топик располагается на нескольких страницах: Ctrl  назад   1 [2]      все
 Re: Описание REST API  [new]
Bsplesk
Member

Откуда:
Сообщений: 113
Petro123
Bsplesk,
старческое брюзжание?


Старческое .....
Не нервничайте, все хорошо. Нет у меня ни времени, ни желания наводить какие-то там порядки, тем более в REST сервисах порядок ограничен исключительно соглашением конкретного REST или не REST API (создать соглашение - это задача архитектора в случае отсутствия спецификации).
Единых спецификаций(как в случаях c SOAP/Odata/graphql...etc) для сервисов аля REST нет в принципе.
Каждый создает свою спецификацию в рамках своих задач вводя те или иные расширения, которые не вписываются в CRUD.
Убедится в этом легко, достаточно рассмотреть пару реальных API:
  • https://developer.atlassian.com/server/confluence/confluence-server-rest-api/
  • https://developer.paypal.com/docs/api/overview/#api-requests
  • https://developer.americanexpress.com/documentation#api-standard-practices
  • https://docs.gitlab.com/ee/api/lint.html (уже сбежали на graphql).
  • https://docs.aws.amazon.com/apigateway/api-reference/link-relation/model-generate-template/

    Пример с amazon API который использует: Link Relations:

    REST API Reference-->Link Relations-->model:generate-template

    model:generate-template

    Generates a sample mapping template that can be used to transform a payload into the structure of a model.

    amazon
    HTTP Request
    GET /restapis/<restapi_id>/models/<model_name>/default_template


    confluence

    Converting content
    Convert storage format to view format

    This example shows how to convert storage format to view format.

    confluence
    curl -u admin:admin -X POST -H 'Content-Type: application/json' -d'{"value":"<ac:structured-macro
    ac:name=\"cheese\" />","representation":"storage"}'
    "http://localhost:8080/confluence/rest/api/contentbody/convert/view" | python -mjson.tool


    paypal
    Executes a PayPal payment that the customer has approved. You can optionally update one or more transactions when you execute the payment.
    paypal
    POST: /v1/payments/payment/{payment_id}/execute


    p.s. говорят execute - это глагол .....
  • 26 сен 18, 12:29    [21686553]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Petro123
    Member

    Откуда: Загрузочный сектор Москвы (AutoPOI.ru)
    Сообщений: 38643
    Bsplesk
    Единых спецификаций(как в случаях c SOAP/Odata/graphql...etc) для сервисов аля REST нет в принципе.
    Каждый создает свою спецификацию в рамках своих задач вводя те или иные расширения, которые не вписываются в CRUD.
    да.
    Я же вам привёл пример с нормализацией.
    Коммунизма в конце концов)).
    Нет спецификации, но есть практика и стремления.
    Недаром есть термин rest, и потом добавили fullRest))).
    Вам прямо надо всех построить по спецификации)).
    Удачи!
    26 сен 18, 13:49    [21686698]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    maslinka
    Member

    Откуда: от верблюда
    Сообщений: 286
    в какой нотации описать лучше API?
    26 сен 18, 15:43    [21686913]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    skyANA
    Member

    Откуда: Зеленоград
    Сообщений: 26479
    maslinka,

    ReDoc: https://github.com/Rebilly/ReDoc
    26 сен 18, 16:07    [21686954]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    skyANA
    Member

    Откуда: Зеленоград
    Сообщений: 26479
    maslinka,

    там сразу и пример открыть можно: https://rebilly.github.io/ReDoc/
    26 сен 18, 16:15    [21686967]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Bsplesk
    Member

    Откуда:
    Сообщений: 113
    maslinka
    в какой нотации описать лучше API?


    maslinka,

    Спецификации (не инструменты отображения или создания):
    В зависимости от задач:
  • дубовых синхронных API: OpenAPI2/3 (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
  • дубовых асинхронных (WebSocket/HTTP2 в вебе): OpenAPI3(https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) или asyncapi (https://www.asyncapi.com/v1/guide/)

    гибких (аля sql - запрос):
    Odatav4: https://www.odata.org/documentation/
    graphql: http://facebook.github.io/graphql/

    ReDoc - хорош для генерации документации по готовому контракту(спецификации OpenAPI 2/3).

    Ну и классика: https://www.w3.org/TR/wsdl/ (но это XML подобное, не модное).
  • 26 сен 18, 17:57    [21687199]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Bsplesk
    Member

    Откуда:
    Сообщений: 113
    Предварительно следует определить языки программирования на котором будет разработано API, а также тех кто будет это api использовать. Также следует ознакомится с поддержкой в конкретном языке (это прямо влияет на скорость разработки) данной спецификации (возможность генерации кода по контракту и наоборот по коду контракт ...).
    Хотя killer feature REST подобных API, что с ними легко начать работать на любом языке, в котором есть поддержка http, просто прочитав соглашение, которое может сгенерировать тотже ReDoc.
    26 сен 18, 18:07    [21687216]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Red1zko
    Member

    Откуда:
    Сообщений: 2
    Уж не знаю на сколько поможет наконец закончить рассуждения в этом топике моя личная практика, но на данный момент я делаю так:
    1. Получаю задачу на разработку (роль архитектор/аналитик тут не причем)
    2. Собираю бизнес требования к задаче, формирую простой документ где описываются все потребности бизнеса
    3. Исходя из получившейся доки формирую ТЗ на разработку
    и выглядит это следующим образом:
    - собираю объектную модель в ЕА
    - для разработчика модель данных в ЕА (очень удобно, на основании нее можно получить кучу sql для разворачивания практически любой БД особо не вникая в тонкости)
    - определяюсь с контрактом для API (лучшее что нашел - для команды с развязанными руками это swagger hub, для команды которой приходиться постоянно выпрашивать это ready api smart bear)
    - на основании контракта поднимаю mock сервис с простейшей логикой
    - логику работы внутри API описываю с помощью activity диаграммы в ЕА
    - логику работы между front и back описываю с помощью activity диаграммы в ЕА
    - прецеденты использования через use case диаграммы в ЕА
    - интеграционные взаимодействия через componet model диаграммы в ЕА (микросервисы родненькие)
    - описание протоколов, серверов и что где должно крутиться через deployment диаграмму.
    Ну и конечно венцом всего этого является автоматическая генерация документа в ЕА (правда посидел настраивая шаблон)
    27 сен 18, 16:28    [21688354]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Petro123
    Member

    Откуда: Загрузочный сектор Москвы (AutoPOI.ru)
    Сообщений: 38643
    Red1zko
    Уж не знаю на сколько поможет
    не поможет, т.к. это обо всём процессе производства ПО "человеком оркестром".
    27 сен 18, 16:36    [21688367]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Red1zko
    Member

    Откуда:
    Сообщений: 2
    Petro123, ну можно же разделить этот процесс по ролям и так будет даже быстрее(правда не проще, но это уже на вкус и цвет)
    27 сен 18, 16:53    [21688380]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    alex55555
    Member [заблокирован]

    Откуда:
    Сообщений: 2129
    Red1zko
    1. Получаю задачу на разработку (роль архитектор/аналитик тут не причем)

    Очень даже "при чём".
    Red1zko
    собираю объектную модель в ЕА
    - для разработчика модель данных в ЕА ...
    - определяюсь с контрактом для API ...
    - на основании контракта поднимаю mock сервис с простейшей логикой
    - логику работы внутри API описываю с помощью activity диаграммы в ЕА
    - логику работы между front и back описываю с помощью activity диаграммы в ЕА
    ...
    - интеграционные взаимодействия через componet model диаграммы в ЕА...
    - описание протоколов, серверов и что где должно крутиться через deployment диаграмму..

    Вот так примерно уг и получается. Садят "аналитика" на некую задачу, а этот перец ни ухом ни рылом в архитектуре, но очень верит в себя и страждет нарисовать шедевр. Ну и конечно, в шедевре ничего не получится, если "аналитик" сам не поковыряется абсолютно во всём. Поэтому перца тянет на ... ну в общем на абсолютно всё. Он даже слышал, что код ему писать не надо, но ведь шедевр пропадёт! И потому он как минимум на SQL наваяет какую-нибудь элементарную хрень, которой потом будет в нос всем тыкать - вот, смотри как у меня просто, а ты что наворотил?! Ну и разумеется, как же без деплоймента! Ога, оналитег и про это абсолютно всё-всё знает! И очень хочет это всем доказать. Ну и в общем рожает этакого ублюдка, которого в страшном сне не увидишь, но автор с пеной у рта всем будет доказывать - это шедевр! Осталось сказать "я так вижу", но оналитег знаком с соответствующим произведением, а потому выбирает немного другие фразы. Но суть та же.

    В целом те придурки, которые наняли, а самое главное - дали вот так безобразничать этому оналитегу, получают гарантированное уг, от него все плюются, но что толку? Придурки знают, что надо через аналитика работать. Но как - они не знают. Ну и отдают инициативу самому крикливому. И когда таким крикливым оказывается оналитег - ну в общем картина Репина "приплыли". Хотя если таким крикливым окажется программист, то картина тоже получается ... может и не Репина, но какой-нибудь Савраска в ней обязательно присутствует и тянет свою телегу, и обязательно поперёк МКАД-а. А чо, это же эффективно!
    27 сен 18, 20:01    [21688514]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    maslinka
    Member

    Откуда: от верблюда
    Сообщений: 286
    Red1zko
    Уж не знаю на сколько поможет наконец закончить рассуждения в этом топике моя личная практика, но на данный момент я делаю так:
    1. Получаю задачу на разработку (роль архитектор/аналитик тут не причем)
    2. Собираю бизнес требования к задаче, формирую простой документ где описываются все потребности бизнеса
    3. Исходя из получившейся доки формирую ТЗ на разработку
    и выглядит это следующим образом:
    - собираю объектную модель в ЕА
    - для разработчика модель данных в ЕА (очень удобно, на основании нее можно получить кучу sql для разворачивания практически любой БД особо не вникая в тонкости)
    - определяюсь с контрактом для API (лучшее что нашел - для команды с развязанными руками это swagger hub, для команды которой приходиться постоянно выпрашивать это ready api smart bear)
    - на основании контракта поднимаю mock сервис с простейшей логикой
    - логику работы внутри API описываю с помощью activity диаграммы в ЕА
    - логику работы между front и back описываю с помощью activity диаграммы в ЕА
    - прецеденты использования через use case диаграммы в ЕА
    - интеграционные взаимодействия через componet model диаграммы в ЕА (микросервисы родненькие)
    - описание протоколов, серверов и что где должно крутиться через deployment диаграмму.
    Ну и конечно венцом всего этого является автоматическая генерация документа в ЕА (правда посидел настраивая шаблон)

    мы реализуем примерно это же)
    2 окт 18, 09:26    [21692211]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    Serguei
    Member

    Откуда: Papua New Guinea
    Сообщений: 647
    Red1zko
    - для разработчика модель данных в ЕА (очень удобно, на основании нее можно получить кучу sql для разворачивания практически любой БД особо не вникая в тонкости)


    Можно попросить вас уточнить вот этот момент. Вы из ЕА генерируете скрипты на создание/изменение структуры БД? Что то я отстал от жизни, если там такое возможно.
    2 окт 18, 13:43    [21692590]     Ответить | Цитировать Сообщить модератору
     Re: Описание REST API  [new]
    maslinka
    Member

    Откуда: от верблюда
    Сообщений: 286
    Red1zko
    получить кучу sql для разворачивания практически любой БД особо не вникая в тонкости)

    фраза противоречивая. )
    2 окт 18, 14:40    [21692720]     Ответить | Цитировать Сообщить модератору
    Топик располагается на нескольких страницах: Ctrl  назад   1 [2]      все
    Все форумы / Разработка информационных систем Ответить