Как получить несколько ответов от одной конечной точки с разными параметрами?

Мы рассматриваем возможность использования API Blueprint. Есть случаи, когда мы хотели бы, чтобы один запрос возвращал правильный ответ, а другой запрос возвращал ответ «ошибка», такой как 400 bad request, чтобы другие разработчики могли работать с фиктивным API на apiary.io с обоими типами ответов и обрабатывать его. в своих приложениях.

Я создал совершенно произвольный пример ниже,

## Thing [/thing/{id}]
Gets a thing but the thing id must be a prime number!


+ Parameters
    + id (string) ... ID of the thing, a prime number!

+ Model (application/json)

    The thing itself.

    + Body

            {
                "description": "It is green"
            }

### Retrieve a Single Gist [GET]
+ Response 200

    [Gist][]

Теперь как-то я хотел бы добавить в ответ для /thing/40

+ Response 400
    {  "error" : "Invalid request" }

Но я не уверен, как бы я сделал это с помощью API Blueprint. Это было достижимо в «старом» стиле на apiary.io, но мы хотели бы перейти к новому синтаксису.


apiary.io apiblueprint
person Mendhak    schedule 22.01.2014    source источник

Ответы (2)


arrow_upward
12
arrow_downward

Чтобы задокументировать несколько ответов, просто добавьте его после Response 200 следующим образом:

## Thing [/thing/{id}]
Gets a thing but the thing id must be a prime number!

+ Parameters
    + id (string) ... ID of the thing, a prime number!

+ Model (application/json)

    The thing itself.

    + Body

            {
                "description": "It is green"
            }

### Retrieve a Single Gist [GET]
+ Response 200

    [Thing][]

+ Response 400 (application/json)

        {  "error" : "Invalid request" }

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

+ Response 400 (application/json)

    This response is returned when no `Thing` for given `id` exists.

    + Body

Если вы используете макет Apiary, имейте в виду, что первый ответ в списке возвращается по умолчанию, если вы не указали иное, используя предпочитать заголовок HTTP.

person Zdenek    schedule 22.01.2014
comment
Понятно, поэтому я не могу специально создать описание/ответ для /thing/40. Могу ли я отправить запрос функции для этого где-нибудь? - person Mendhak; 24.01.2014
comment
Не в структурированном виде. Вы можете комментировать это только устно. Могу я спросить вас, каков ваш вариант использования / зачем вам это нужно? - person Zdenek; 26.01.2014
comment
План состоит в том, чтобы добавить его поддержку в будущую версию API Blueprint, в основном для улучшения тестируемости схемы — github.com/apiaryio/api-blueprint/issues/21, gist.github.com/zdne/ Вы можете ознакомиться и внести свой вклад в дорожную карту API Blueprint по адресу github.com/apiaryio/api-blueprint/issues/milestones - person Zdenek; 26.01.2014
comment
Несколько пар запрос/ответ теперь доступны как Несколько транзакций в спецификации API Blueprint. - person bernhardw; 15.09.2014

arrow_upward
1
arrow_downward

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

Бронирование [/reservation/{reservation_key}]

Объект Reservation имеет следующие атрибуты:

  • номер комнаты
  • Reserved_at — дата публикации вопроса в соответствии со стандартом ISO8601.

  • booker_details — объект Booker.

  • Параметры

    • reservation_key (required, text, 1) ... Reservation Key ash

Просмотр сведений о бронировании [GET]

  • Ответ 200 (приложение/json)

    {
    "room_number": 55,
    "reserved_at": "2014-11-11T08:40:51.620Z",
    "booker_details": 
        {
            "name": "Jon",
            "last_name": "Doe",
        }
}

Бронирование [/reservation/notarealreservation123]

Использование несуществующего бронирования (пожалуйста, используйте notarealreservation123 в подделке) возвращает не найдено

person Bizmate    schedule 24.04.2015