How to represent URI query parameters in JSON hyper-schema

[Amit J]

Hi,

I am trying to use JSON schema as the REST service definition format. I am working on exposing a tooling for creating REST services. Client side tooling would depend on the service definition for understanding the REST operations. 

In LDO for GET requests I generate the following: 

                   {

"rel" : "search",

"href" : "/orders",

"schema" : {

"type" : "object",

"properties" : {

"drink" : {

"type" : "string"

}

}

}

}            

As per my understanding, for GET requests, schema properties implicitly define the query parameters. Please correct me if this is not a right way to represent the query parameters.

Now consider a LDO for the PUT operation

{

            "title": "Pay for the order",

                "rel" : "payment",

                "href" : "/payments",

                "method" : "POST",

                "schema" : {

"type" : "object",

"properties" : {

"drink" : {

"type" : "string"

}

}

}

          }

How shall we represent query parameters for PUT operation. PUT request with query parameters may not make sense but as a tool provider I need to allow user to do it. Schema in this case describes the request schema (not the query params unline in GET method)

Appreciate your help.

[Geraint]

Are these query parameters coming from the data, or from user/client input?

The spec currently only allows adding user/client input to either the URL (for GET/etc.) or to the body (for PUT/etc.).  It's kinda similar to the way HTML forms work - the user-generated inputs are either all in the query (method="GET") or all in the body (method="POST"), and you can't mix-and-match.

However, if the parameters are coming from the data, (e.g. "/payments?id=12345") then the appropriate way to describe this is a URI Template in "href":

{

    "type": "object",

    "properties": {

        "id": {"type": "string"}

    },

    "links": [{

        "href": "/payments{?id}",

        "rel": "edit",

        "method": "PUT",

        "schema": {...}

    }]