Many REST API schemas do not match their response contents

  • Hi,

    I’m working on a tool that uses schema objects from OPTIONS /wp-json/wp/v2 endpoints.

    I noticed that many of them do not represent their GET endpoints.

    GET /wp-json/wp/v2/posts returns the following response, which is an array of Post object

    
[
    {
        "id": 1,
        "date": "2022-07-06T08:15:30",
        "date_gmt": "2022-07-06T08:15:30",
        "guid": {
            "rendered": "https://woodev.local/?p=1"
        },
        "title": {
            "rendered": "Hello world!"
        },
        "content": {
            "rendered": "\n<p>Welcome to WordPress. This is your first post. Edit or delete it, then start writing!</p>\n",
            "protected": false
        },
        ...
    }
]

    OPTION /wp-json/wp/v2/posts returns the following schema

    
{
    "$schema": "https://json-schema.org/draft-04/schema#",
    "title": "post",
    "type": "object",
    "properties": {
        "date": {
            "description": "The date the post was published, in the site's timezone.",
            "type": [
                "string",
                "null"
            ],
            "format": "date-time",
            "context": [
                "view",
                "edit",
                "embed"
            ]
        },
        "date_gmt": {
            "description": "The date the post was published, as GMT.",
            "type": [
                "string",
                "null"
            ],
            "format": "date-time",
            "context": [
                "view",
                "edit"
            ]
        },
        ....
    }
}

    It only represents a single Post. Shouldn’t it return the following schema instead?

    {
    "$schema": "https://json-schema.org/draft-04/schema#",
    "title": "posts",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "date": {
                "description": "The date the post was published, in the site's timezone.",
                "type": [
                    "string",
                    "null"
                ],
                "format": "date-time",
                "context": [
                    "view",
                    "edit",
                    "embed"
                ]
            },
            "date_gmt": {
                "description": "The date the post was published, as GMT.",
                "type": [
                    "string",
                    "null"
                ],
                "format": "date-time",
                "context": [
                    "view",
                    "edit"
                ]
            },
            ....
        }
    }
}
    • This topic was modified 2 years, 4 months ago by moon0326.
    • This topic was modified 2 years, 4 months ago by moon0326.
    • This topic was modified 2 years, 4 months ago by moon0326.
Viewing 6 replies - 1 through 6 (of 6 total)
  • Moderator bcworkz

    (@bcworkz)

    It doesn’t appear the REST API explicitly supports OPTION requests. I say this based on this line in WP_REST_Server class.

    What are you hoping to achieve with an OPTION request?

    Thread Starter moon0326

    (@moon0326)

    @bcworkz According to https://developer.www.ads-software.com/rest-api/extending-the-rest-api/schema/, OPTIONS calls are supported. You can try OPTIONS for most wp/v2 endpoints.

    I’m trying to use schema from OPTIONS calls to build a tool, but having hard time because returned schemas do not match responses.

    From https://developer.www.ads-software.com/rest-api/extending-the-rest-api/schema/, it says the following

    “we are returned the schema of our API, enabling others to write client libraries to interpret our data”

    This isn’t true since schema doesn’t match the response. There needs guessing work to work with schemas

    I’m trying to see if WP community is aware of it. If so, if this is intentional.

    Moderator bcworkz

    (@bcworkz)

    Huh, I wonder why it’s not enummerated in the API server code.

    Anyway, my interpretation is a single post structure is the proper schema for a posts request. The array structure returned for a posts request for multiple objects should be expected, but it doesn’t belong as part of the schema for any particular resource type.

    I suppose the question is should the schema returned be for the type of resource requested, or for the response itself? Since being RESTful is all about resources, I believe defining the resource’s schema and not the response itself is proper.

    Thread Starter moon0326

    (@moon0326)

    @bcworkz

    If the returned schema doesn’t match its endpoint, it’s not possible to build a tool and “we are returned the schema of our API, enabling others to write client libraries to interpret our data” is false in that case because those tools need to guess the type of endpoints — object or array.

    Let’s say I’m building a mock server using schema and I want to provide a mock endpoint for the posts. It’s not possible to build the tool without mapping the endpoint’s type.

    posts => collection
    post => item

    > Since being RESTful is all about resources, I believe defining the resource’s schema and not the response itself is proper.

    We can have both, and that’s what other tools such as OpenAPI (aka Swagger) choose to.

    Once you define a resource (Post in this case), you can reuse it as if it’s a model.

    {
	"type": "array",
	"items": {
		"$ref": "#/schmea/Post"
	}
}

    Maybe I should open a PR and see what others think ??

    Moderator bcworkz

    (@bcworkz)

    It’s worth discussing. I’m pretty sure it’s intentional and not a mistake, but there’s always room for improvement. Instead of a PR, the best place to discuss is in a Trac ticket. Please ensure a similar ticket has not already been posted before creating a new one.

    Thread Starter moon0326

    (@moon0326)

    @bcworkz Thank you! I did not know about Trac system.

Viewing 6 replies - 1 through 6 (of 6 total)
  • The topic ‘Many REST API schemas do not match their response contents’ is closed to new replies.