What is the standard outcome of the following 'remove' JSON Patch with an empty "" path?
[{ "op": "remove", "path": ""}]
Should it clear the whole object, equal to assigning {}? In http://jsonpatch.com/ it says: To point to the root of the document use an empty string for the pointer. So I guess a 'remove' on the root removes the whole object, right?
I tried it with two different JSON Patch libraries with two different results:
https://github.com/java-json-tools/json-patch: deletes the whole object
https://github.com/gnieh/diffson: throws an JsResultException
What is the officially accepted, standard outcome of this? I checked in the RFC for the JSON Patch (https://www.rfc-editor.org/rfc/rfc6902) but couldn't find anything.
RFC 6902 references this for further error handling: https://www.rfc-editor.org/rfc/rfc5789#section-2.2
And to me, this part seems to fit the bill:
Resource not found: Can be specified with a 404 (Not Found) status
code when the client attempted to apply a patch document to a non-
existent resource, but the patch document chosen cannot be applied
to a non-existent resource.
Since you basically did not define any resource - not even / which would more clearly refer to the root / the entire object.
I guess the difference in the two libraries comes from that these two are usually considered identical:
/my/resource
/my/resource/
But usually the non-/ path would be automatically 301 Redirected to the path that does have /. So I would personally go with the 404 response for "path": ""
Related
I'm learning REST webservices and I've been assigned the task of wrapping (creating a new JSON schema on top of) an existing REST API for which I have been given its JSON schema. The schema that I am wrapping specifies a "pattern": "^(.*)$" for properties (such as city or streetAddress) that are of "type": "string". The regex matches everything until a line terminator is encountered. I know that the REST API that I am wrapping in turn wraps a SOAP message (and may have been mechanically converted from SOAP to JSON - so I suspect a conversion artifact is at work here).
My question is, is this a typical pattern to apply to strings passed to and from webservice endpoints or is it's specificity redundant and unnecessary?
My thought is that the generation of this pattern within the JSON schema is an artifact of the automated conversion process and as such it would make sense to simplify my wrapper by omitting the "pattern": "^(.*)$".
I would make an informed guess that someone has previously taken a JSON instance, and used a tool to generate some or all of the JSON Schema files you are looking at.
I couldn't tell you why they have done this, but it seems pretty pointless.
It could be to make sure there are no line breaks in each of those fields, but I've also seen this in generated schemas more than a few times.
I'm trying to build a JSON schema (draft-06) for an existing JSON data file. The schema has gotten to big to fit in a single file and I am trying to break it up into multiple files. However I keep getting the error can't resovle refrence sectionTableSchema.txt from id http://somesite/section
I've made the following files and placed them in the same directory. These files are not hosted on a webserver.
settingsSchema.txt:
{
"title":"Settings",
"$schema":"http://json-schema.org/draft-06/schema#",
"$id":"http://somesite/settingsSchema.txt",
"properties":{
"section":{
...
...
...
"$id":"/section",
"items":{
"oneOf":[
{"$ref":"#/sectionTableSchema.txt"},
{"$ref":"#/sectionNonTableSchema.txt"}
]
},
"type":"array"
}
},
"type":"object"
}
sectionTableSchema.txt
{
"$schema":"http://json-schema.org/draft-06/schema#",
"$id":"http://somesite/sectionTableSchema.txt",
"definitions":{},
"properties":{
....
....
....
}
"type":"object"
}
I think part of my issue is that I don't understand the $id and $ref keywords enough to know what is going on between absolute uri, relative uri, json-pointers and the like.
What happens?
In the OP's example "$ref":"#/sectionTableSchema.txt" means "inside current schema file, get JSON property called sectionTableSchema.txt from root element".
How $ref works?
$ref can be presented in two parts:
Before "#" sign you can specify URI (in simple words, a path) of schema file. If you start $ref from "#" sign and, therefore, don't provide URI of schema file, this means you want to take schemas from current file.
After "#" sign you can provide a JSON pointer, e. g. a path to the property in JSON that is located in specified file (or current file, depending on provided schema URI before "#" sign).
The same information can be found in documentation.
How to reference other file correctly?
As I understand, JSON Schema drafts say you can specify a valid URI to schema file. But URIs cannot be relative, so there is no standard-defined way of referencing files with relative paths. However, in practice a lot of tools provide abilities to do this, though they are not a part of the standard and may differ from tool to tool.
In AJV you can write your reference as "$ref":"ANY-ID-YOU-WANT" and use ajv.addSchema(schemaJson, 'ANY-ID-YOU-WANT') method, where schemaJson is a variable with require'd sectionTableSchema.txt content.
Is it possible to use invalid(non existing) Uri for JSON schema definition?
So that I can specify it and use for versioning, without need to deploy it anywhere?
A URL is expected to resolve to the resource, so if you say "this is the URL for the schema" then that URL should resolve to the schema.
However, URLs are not the only sort of URI - it sounds like a URN might be what you want. In contrast to a URL (uniform resource location), a URN (uniform resource name) is an identifier for a resource, but it doesn't carry a generic method to resolve it.
For example, the URN urn:ietf:rfc:2648 is an identifier for RFC 2648, but there isn't a standard way to get the RFC text from just that URN (you'd need some kind of special service that knew about urn:ietf:rfc:... URNs). If you used something like this, then it should (in theory) do what you want.
(You might run into trouble referencing one schema from another if your library is mistakenly assuming all URIs are URLs, but that would be a bug in your library.)
I have (JSON for) a resource like this at /api/foo/1/
{name: "foo", bar_pks: [10, 11, 12]}
Now I want to add an API for appending to bar_pks. There is no HTTP verb for appending I can find. If I do a patch to /api/foo/1/ with {bar_pks: [13]}, it will overwrite, not append.
Is there a verb more consistent with appending?
If I modify patch for this resource to always do an append, will it come to bite me later?
(I am using Django and Tastypie, but would prefer a language agnostic answer.)
Is there a compelling reason not to do the append on the client side and use a PUT/PATCH to send the updated value back to the server?
I see a couple of options if you're dead-set on doing this:
A POST to a new URI which gets interpreted as a an append to the
list.
A query parameter on the PATCH which indicates that the
changes should be appended rather than overwrite.
Neither of these are good options, and I do not endorse using them.
I stumbled over a practice that I found to be quite widespread. I even found a web page that gave this a name, but I forgot the name and am not able to find that page on google anymore.
The practice is that every JSON response from a REST service should have the following structure:
{
"status": "ok",
"data": { ... }
}
or in an error case:
{
"status": "error",
"message": "Something went wrong"
}
My question: What is the point why such a "status" property should be required in the JSON? In my opinion that is what HTTP status codes were made for.
REST uses the HTTP means of communication between client and server, for example the "DELETE" verb should be used for deleting. In the same way, 404 should be used if a resource is not found, etc. So inline with that thinking, any error cases should be encoded properly in the HTTP status.
Are there specific reasons to return a HTTP 200 status code in an error case and have the error in the JSON instead? It just seems to make the javascript conditional branches more complex when processing the response.
I found some cases where status could be "redirect" to tell the application to redirect to a certain URL. But if the proper HTTP status code was used, the browser would perform the redirection "for free", maintaining the browsing history properly.
I picture mainly two possible answers from you:
Either there are two quarreling communities with their favorite approach each (use HTTP status always vs. use HTTP status never)
or I am missing an important point and you'll tell me that although the HTTP status should be used for some cases, there are specific cases where a HTTP status does not fit and the "status" JSON property comes into play.
You are right. I think what you are seeing is a side-effect of people not doing REST correctly. Or just not doing REST at all. Using REST is not a pre-requisite for a well-designed application; there is no rule that webapps have to be REST-ful.
On the other hand, for the error condition, sometimes apps want to return a 200 code but an error to represent a business logic failure. The HTTP error codes don't always match the semantics of application business errors.
You are mixing two different Layers here:
HTTP is for establishing (high-level) connections and transferring data. The HTTP status codes thus informs you if and how the connection was established or why it was not. On a successful connection the body of the HTTP request could then contain anything (e.g. XML, JSON, etc.), thus these status code have to define a general meaning. It does not inform you about the correctness or type (e.g. error message or data) of the response.
When using JSON for interchanging data you could certainly omit the status property, however it is easier for you to parse the JSON, if you know if it includes the object you were requesting or an error message by just reading one property.
So, yes, it is perfectly normal to return a 200 status code and have a "status": "error" property in your JSON.
HTTP status codes can be caused by a lot of things, including load balancers, proxies, caches, firewalls, etc. None of these are going to modify your JSON output, unless they completely break it, which can also be treated as an error.
Bottom line: it's more reliable to do it via JSON.