maslinka,

Смотри, большинство документаций api это не просто текст - это контракт/договор(описание интерфейса взаимодействия с сервисами, которые предоставляет API), по которому можно сгенерировать исходный код без логики реализации и обратно (вот этот код можно описать в UML - но зачем? по факту описания swagger достаточно - если, конечно, нет цели вести описание "объектов" централизованно и переиспользовать объекты,структуры данных) .
Чисто - документация это позапрошлый век.

Есть два основных подхода:
- contract first
- code first
Для начала тебе нужно определить каким образом было/будет разработано? данное API.
Если API уже есть и контракт, то можно забить, пофик, как реализовано.

Что нужно то?

- Описать API? Swagger и есть описание/контракт(интерфейс). Отвечает на вопрос: Как работать с сервисами предоставляемыми данным API? - больше ничего не требуется, всё должно быть описано в контракте.
- Создать описание работы реализованных сервисов(еще называют паспортами сервисов) API ?, Отвечает на вопрос: как работает сервис (внутри) - обычно рождается после разработки по ТЗ или без ТЗ(Отвечают на вопросы, как должен быть разработан/доработан данный сервис), служит вводной для нового разработчика/тестировщика/архитектора/аналитика. Обновляется в течении жизни сервиса, обычно текст + дополненный UML/ER диаграммой по необходимости. Самое сложное, рутинное, блевотное.
- Описать интеграционные потоки взаимодействия с сервисами данного API (обычно часть паспорта), текст + UML Sequence/BPMN. Отвечает на вопрос: Кто и как взаимодействует/использует с данным сервисом.

P.S.
Одна модель данных описанная на (на форме) к примеру маппится на соответствующую модель описанную в swagger.
С этим в UML - ЖОПА, ПОЛНАЯ.

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

Data Mapping in UML
Written by DT_Sam

It’s often the case that we need to map various attributes on entities into other entities. For example you might need to migrate data from one system to another and structurally the same concepts are held slightly differently. Documenting these mappings is not obvious in the UML, so below I’ve provided a simple example of how a composite structure diagram could be used to provide the mappings. Some notes have been added where conversions need to be performed and these could be represented more formally using diagram references to behavioural diagrams such as sequence or activity diagrams. This is quite possibly not 100% UML compliant / intended usage; but it provides a tool for this type of mapping which otherwise seems to be lacking in the standard UML specification.


https://community.sparxsystems.com/white-papers/623-95data-mapping-in-uml
http://www.sparxsystems.com/forums/smf/index.php?topic=25999.0

Используете: Excel/altova mapforce... etc
К текстовому описанию логики маппинга(сопоставления) - можно приложить uml activity, но обычно там все просто и достаточно текста.

Petro123maslinkaну так как я не разработчик мне многие задачи для понимания даются очень сложно
Построение урл для ресурса с REST API:
https://restfulapi.net/resource-naming/

offtop

REST - это круто :).
Простейший пример: есть клиент, есть карта, у карты есть pin и cvc, вещи эти отдельные, в одном объекте несовместимые, эти данные хранить нельзя они вычисляются при каждом запросе и передаются по разным каналам в одну операцию(вычисли и отправь - разделить на два метода нельзя, ибо хранить эти данные запрещено), при этом cvc динамический - id у него нет:

Как предлагается реализовывать соответствующий REST?

GET: /clients/{clientId}/cards/{maskedPan}/cvc ?
POST: /clients/{clientId}/cards/{maskedPan}/cvc ?

Всё, приехали - CRUD для описанной выше задачи не катит, он вообще мало для чего катит на самом деле

Что "новопридуманный" контроллер делать? - а по факту функцию, привет удаленный вызов процедур(RPC), и причем тут REST :) ?

controller

A controller resource models a procedural concept . Controller resources are like executable functions , with parameters and return values; inputs and outputs.

Use “verb” to denote controller archetype.

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play
-------------------------------------------------

POST: /clients/{clientId}/cards/{maskedPan}/cvc/ send ?
или
POST: /clients/{clientId}/cards/{maskedPan}/ cvcSending / send ?

Petro123BspleskREST - это круто :).
Простейший пример: есть клиент, есть карта, у карты есть pin и cvc
А причём тут REST?
Просто неверный выбор технологии для задачи.

Она же у нас 2-3:1 аналитик/архитектор.
Вероятно ей рано или поздно придется участвовать в проектировании API.
В том числе заниматься выделением бизнес объектов ой ресурсов и их связей (да, да те самые 1-1, 1-N ... etc), который станут "строительными блоками api", а REST сейчас пихают куда только можно и нельзя (хотя хайп пошел на спад). Тут приведена простая, тривиальная бизнес задачка не влезающая в рамки пропагандируемых реализаций архитектурного стиля REST.
Ей, как аналитику/архитектору нужно уметь "Впихнуть невпихуемое", а лучше уметь отстаивать свою точку зрения.


skyANABsplesk, вот:

Rest. А как реализуются методы с логикой сложнее чем Добавить/Удалить ?

Что вот? три страницы срача? - точнее "как натянуть сову на глобус", достаточно посмотреть реализации многих API TOP компаний, чтобы понять, что каждый сам как может у каждой компании свое видение.

https://restfulapi.net/resource-naming/ --> тут же в комментариях "срач" аналогичный.

Sean says
November 8, 2017 at 6:25 am
checkout is a verb and play are verbs and as you point out at the start it is considered bad practice to use verbs in the URI.
“RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb)”
Also you haven’t mentioned which HTTP method should be called for the controller pattern but if it is GET then you are changing state via a method that should be idempotent.
If it is POST then the controller pattern is RPC rather than REST . A RESTful API would allow the retrieval of the “checkout” resource via
“GET http://api.example.com/cart-management/users/{id}/cart/checkout”
which doesn’t seem to make sense as a request.
It would be better IMO to include a status attribute in the cart resource and update that.

Что предлагает господин admin? - правильно очередное костылище, используйте, что угодно, но только не вздумайте обозвать с чем-то логически намекающем на: CRUD.
Итого имеем не CRUD, а CRAHCFFDERTFCVFDSTRDCVGFCERSDFYUIKLPOKJYUFRSDFVBYFYGTRDREDCVGFJHCRYSDXCFCFCV, простое логичное api.

Admin says

November 10, 2017 at 11:50 pm

We can put actions in controller resources which are not logically mapped to any of CRUD operations e.g.
POST /device-management/{id}/alerts/{id}/resend

Above operation does not fall under CRUD.

Выше дан более интересный пример, когда операцию даже "разложить" не представляется возможным в силу описанных требований. Есть рассматривать коммент выше - то в описываемом случае нельзя включить status attribute в cart resource.

Всё просто:

Petro123Bsplesk,
старческое брюзжание?

Старческое .....
Не нервничайте, все хорошо. Нет у меня ни времени, ни желания наводить какие-то там порядки, тем более в 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.

amazonHTTP 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.

confluencecurl -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 - это глагол .....

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 подобное, не модное).

Предварительно следует определить языки программирования на котором будет разработано API, а также тех кто будет это api использовать. Также следует ознакомится с поддержкой в конкретном языке (это прямо влияет на скорость разработки) данной спецификации (возможность генерации кода по контракту и наоборот по коду контракт ...).
Хотя killer feature REST подобных API, что с ними легко начать работать на любом языке, в котором есть поддержка http, просто прочитав соглашение, которое может сгенерировать тотже ReDoc.