Should hyper-schema support non-RESTful HTTP APIs? #88
Comments
|
Adding support for new headers and methods doesn't seem terribly different than adding support for JSON Hyper-Schema. If people can't be bothered to use HTTP correctly in the first place, for what reason would they potentially end up using the hypermedia functionality of JSON Schema? |
Interaction with legacy systems is the primary use case. People and companies learn, and start doing things better. And maybe even right. But there are many reasons why it may not be feasible to update a legacy system, which may need a lot more than the addition of new headers or methods in order to bring it into compliance. I can give you a concrete example in email if you'd like- I don't want to go into specifics of current projects in a GitHub issue :-) |
|
Mark Nottingham (HTTP author) appears to be doing some work in this area, see https://www.ietf.org/id/draft-nottingham-json-home-04.txt |
Interesting. I was aware of this but hadn't yet gotten around to reading through it. It's more relevant than I had guessed. I need to think about how JSON Hyper-Schema and JSON Home could be used together on a legacy API, but this may be a solution. I would actually prefer a solution that isolates support for non-compliant APIs somewhere else. |
|
I agree this is best pursued through JSON Home. I may open specific issues in the future for things that seem to fall through the cracks between the projects, but I have no particular concerns right now. I think that expecting proper HTTP use is another principle that can go in issue #55 |
|
I wasn't suggesting JSON Home should be used instead, in all likelihood But he does know how to design protocols, it's worth learning from. The On Oct 12, 2016 2:13 PM, "Henry Andrews" [email protected] wrote:
|
|
@awwright feel free to re-open if you think we should support noncompliant HTTP use with Hyper-Schema. We'll probably take a year or two to get to RFC as well :-P |
Some of the concerns I have raised in issue #48 are motivated by an assumption that JSON Hyper-Schema should be usable to describe any HTTP API, including those that abuse HTTP. Is this a goal, or is full and proper use of HTTP a prerequisite for being able to create a usable hyper-schema?
We can complain about it as much as we want (and I often do), but many real-world HTTP APIs abuse the HTTP spec. People still write APIs that tunnel everything through POST. They don't set
Accept-Patchwhen they're using PATCH. They implement partial updates with PUT. Or POST.In order to support these APIs, JSON Hyper-Schema would need ways to explicitly map operations to HTTP methods, requests, and responses. Specifically
method(or some other keyword) would need to allow specifying the actual HTTP (or other protocol) method to be used, along with usingschemato describe non-standard request formats such as PUT requests that are not proper representations.The "get"/"set"/"create"/"delete" links in the alternate format that I'd used in the past (which puzzled @awwright in issue #48 ) were never (intentionally) used to override HTTP behavior in newly designed APIs. But they did allow using the same tooling with old APIs, some of which may not have used HTTP fully or correctly.
Being able to retrofit legacy APIs with JSON Hyper-Schema to allow them to be used in the same tooling ecosystem seems very desirable to me to facilitate adoption.
The text was updated successfully, but these errors were encountered: