Конечная точка API, принимающая изменяемый набор данных

Question

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

Answer 1

Возврат Http 400 Bad Request с ответом JSON, содержащим URL-адрес схемы JSON, которой должна соответствовать полезная нагрузка. Отдельная конечная точка, возвращающая схему JSON, также является опцией.

Я не знаю вашего случая, но мне не нравится идея "изменяемого набора данных". Может быть, вы можете подумать о редизайне вашего API или оборачивании ваших наборов данных в вид контейнера, чтобы все они могли быть описаны одной JSON-схемой? (как в примере ниже)

{
            "oneOf": [
                {
                    "type": "object",
                    "required": [ "domain", "content" ],
                    "properties": {
                        "domain":{"type": "string", "enum": ["domain1"]},
                        "content": {"type": "string"}
                    }
                },
                {
                    "type": "object",
                    "required": [ "domain", "content" ],
                    "properties": {
                        "domain":{"type": "string", "enum": ["domain2"]},
                        "content": {"type": "number"}
                    }
                }
            ]
}

в зависимости от значения «домен», содержимое может быть либо строкой, либо числом

Answer 2

Потенциальный API с самоописанием, который вы ищете: ОПЦИИ HTTP-запрос.

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

http://zacstewart.com/2012/04/14/http-options-method.html

Для различных возможных наборов данных вы можете использовать пользовательский заголовок Content-Type, например: Content-type: application/vnd+some.payload+json.

Хорошим примером использования этих типов является GitHub API: https://developer.github.com/v3/media/