Гипер-схема JSON: разные схемы для GET и POST

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

Например, я мог бы описать API, в котором элемент может быть создан или обновлен следующим образом: {"name": "Task", "due": "2014-12-31"} или примерно так: {"name": "Task", "due": {"$date": 1419984000000}}, но он всегда возвращается из API только первым способом.

Таким образом, схема для POST / PUT может быть:

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "oneOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "object",
                    "properties": {
                        "$date": {
                            "type": "number"
                        }
                    },
                    "required": ["$date"],
                    "additionalProperties": false
                }
            ]
        }
    }
}

Тогда как схема доступа через GET была бы намного проще:

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "type": "string",
            "format": "date"
        }
    }
}

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

Существует ли какой-либо общепринятый стандартный подход для указания различных схем в контексте гипер-схемы JSON? Я думал об указании этих различий с помощью свойства "links", но я не знаю, в каком "rel" я бы определил эти схемы, и это кажется очень нестандартным.


json jsonschema
person lyschoening    schedule 11.09.2014    source источник

Ответы (1)


arrow_upward
4
arrow_downward

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

{
  "description": "create an item.",
  "href": "/items",
  "method": "POST",
  "rel": "create",
  "schema": {
    "$ref": "#/api/createitem"
  },
  "title": "Create an item"
}

Фактическая требуемая схема указывается в свойстве "schema" через "$ ref".

Если вы также хотите описать типы ответов, вы можете использовать свойство targetSchema. Имейте в виду, что это носит рекомендательный характер (поскольку это объясняется в документации )

person jruizaranguren    schedule 11.09.2014
comment
Верно, но этот ("create") предназначен только для создания элемента, а не для его обновления, а "update" не входит в стандарт. - person lyschoening; 11.09.2014
comment
update не является допустимым типом отношения. Ознакомьтесь со следующим RFC: rfc-editor.org/rfc/rfc5988.txt Я думаю, вы путаете типы отношений с операциями CRUD. Похоже, вам нужны rel: self и href: {id} или какой-либо другой URI, который идентифицирует ресурс, который будет обновлен. - person jruizaranguren; 12.09.2014
comment
Я полагаю, что стандартное отношение было бы edit, хотя оно также довольно неоднозначно . Если rel: self можно повторить дважды (я не уверен, может ли это), может быть нормальный с методом: GET и один для обновления с методом POST. - person lyschoening; 12.09.2014
comment
Можно повторить. GET может иметь себя, экземпляры и многие другие типы отношений. И да, rel: edit был бы хорошим выбором, например, для операции PUT. Очевидно, что для этого необходимы дополнительные документы и примеры (на json-schema.org нет образцов гипер-схемы !!). Лучшим практическим источником, который мне известен, является работа парней из Heroku: блог. heroku.com/archives/2014/1/8/ - person jruizaranguren; 12.09.2014
comment
Я имею в виду повторение, как в случае, когда rel: self присутствует дважды с разными методами. Heroku использует rel: update. - person lyschoening; 12.09.2014
comment
Интересное обсуждение в группе json-schema: groups.google.com/forum / #! searchin / json-schema / hyper-schema / Я думаю, это больше связано с API-дизайном и открытостью. Я надеюсь, что ваш первоначальный вопрос решен (да, у вас может быть несколько схем для разных операций, методов, типов отношений, возвращаемых типов и т. Д., И вы можете использовать несколько типов отношений, чтобы указать клиенту ожидаемое поведение). - person jruizaranguren; 12.09.2014