rest package: JSON schema returned from HTTP OPTIONS?

[smyrman]

It might be a good thing to add support for HTTP OPTIONS requests. Another source describes how you might use them in a more useful way for REST-ful APIs.

These requests should probably return a body containing a (pre-compiled) JSON Schema if enabled. I say "if enabled", because the error handling of the JSON Schema package, and it's brutal rejection of validators that are not supported, will need to be fixed before making this the default.

[smyrman]

Removing help wanted label, until this has been discussed a bit.

@rs, what do you think? The main goal is to allow for UIs to more easily generate forms for an individual resource, including indication of which fields are required, and to generate drop-down selections.

This is not a replacement ticket for generating full Swagger / Open API support.

[rs]

I never saw the OPTIONS method used this way. I don’t see any objection against that idea though.

[smyrman]

I have seen the OPTIONS response used for a similar purpose in this framework:

• http://www.django-rest-framework.org/api-guide/metadata/

They list the "schema" under "POST", and they use a custom format rather than JSON schema.

Using JSON Schema in the body of the OPTIONS schema won't be a perfect solution, but it could help with JS validation of simple fields, e.g. based on String.Allowed, String.MaxLen, String.MinLen and/or String.Pattern.

We could extend on it over time with custom JSON Schema extensions. E.g. how would we tell the UI where to find type-ahed values for a reference-field?

[mishak87]

~~It would be useful to have schema.Schema.MarshallJSONSchema() string and schema.MarshallJSONSchema(map[string]schema.Schema) string to generate JSON Schema.~~ Sorry I missed the example how to generate schema in README 😞

I see this as an requirement for generating Swagger/OpenAPI from code & configuration and serving it at /swagger.yml.

Rest-layer has neat integration with storages and robust API out of the box. Providing schema on OPTIONS or in /swagger.yml would make it easy to integrate with single page application frameworks. For example there are forms generators that need only JSON Schema formschema making basic administration cheap. Combining it with CASL in future, would make even complex systems easy to maintain and reduce amount of SPA code and inconsistencies between frontend and backend.

[smyrman]

@mishak87 as for formschema do you know how it is common to make the schema available to set-up to generate these forms? I.e. which of swagger.yml or OPTIONS requests would be the best fit for that lib?

Btw, third-party efforts on generating a swagger.yml are linked on #53.

[mishak87]

I have still some brooding to do about this topic. Principle I try to follow is to use single source of truth and communicate it to other parts of the system. At the moment I am working on a project where I will apply this principle. I will return to this issue when I have more experience with implementing such system.