I have a REST API where legal JSON submitted to an endpoint will contain a sub tree depending on a "type" declaration in the top level. Something like:
{
...
"mtype": "http:...",
"content": {
.. what goes here is what would be defined by the above "mtype"
Essentially, the 'mtype' is the schema url for what goes into 'content'. But what I'm looking for is the equivalent of <xsd:any>.
It would already be useful if I can put something in there which would instruct the Swagger UI to simply put a large text box there for users to paste a JSON body.
you can return an object of type object with no properties as a response. It's not best practice but it can serve your purposes
I don't know Swagger that well, but I know it's type definition is based on JSON Schema. In JSON Schema, the equivalent of <xsd:any> is {}. The empty schema validates as true for any valid JSON. I expect this should be no different in Swagger.
Related
So I am aware of the fact that you can get the files in a repository by using
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}
API.
The API also supports the q parameter where you can query the resulting json object based on various fields in it.
I wanted to know if one can use this query parameter to fetch the files based on certain extensions?
Like the JSON object also contains a field "mimetype" which defines the mime type of the files.
I did use the following API call
https://api.bitbucket.org/2.0/repositories/{workspace}/openapi/src/master/?max_depth=100&q=path+%7E+%22.js%22&pagelen=100
To fetch all the files which contain the string ".js" in the path parameter.
But while querying the mimetype parameter I was not able to do the same using
https://api.bitbucket.org/2.0/repositories/{workspace}/openapi/src/master/?max_depth=100&q=mimetype+%3D+%22application%2Fjavascript%22&pagelen=100
This call returned error.
Can anybody let me know how can you query based on mimetype or if possible fetch the files based on extension
Note: I know about the Code search API but that is not an option as it has large limitations.
I was working through some code, and noticed:
return new Uri(host: server, path: apiPath, query: query, queryParameters: queryParams);
This code is executed regularly throughout the application, and the only difference was queryParams. So i printed it out:
{Id:[1234], enabled:false}
shows it is a key:value set of: Id:List, enabled:boolean.
The stack trace i get is:
which shows the map and then the trace. #6 points to the above line.
It is looking at false... something with iterating false is what breaks this.
When dealing with the URI and query parameters, it is looking for numerics, lists, and strings but not booleans. In order to resolve this and allow it to function correctly, you will need to do:
{"enabled": false.toString()}
// or
{"enabled": "false"}
and the uri class will set the query parameter accordingly.
The Uri class is located in core library for Dart. When we are using it, we are passing in the created Uri object into an action for a client class,
Client client = new BrowserClient();
which accepts the url as a part of the parameters.
While looking at the errors above though, the Uri class ultimately is unable to properly parse a false value to an accepted value.
When looking at the Code Docs for Uri as per the Dart languages: https://api.dartlang.org/dev/1.25.0-dev.7.0/dart-core/Uri/Uri.html
The query component is set through either query or queryParameters. When query is used, the provided string should be a valid URI query, but invalid characters, other than general delimiters, will be escaped if necessary. When queryParameters is used the query is built from the provided map. Each key and value in the map is percent-encoded and joined using equal and ampersand characters. A value in the map must be either a string, or an Iterable of strings, where the latter corresponds to multiple values for the same key.
Which makes sense to say all values must be String or an Iterable of Strings. The only thing which I cant figure out is that in Dartpad, true and false have toString functions, and yet you can also pass numerics in there.
The only conclusion is that while it accepts Strings and Iterables of Strings, it will also parse ints and other numerics because they will explicitly check for that type as it is common to see in URI.
One would think that the URI would understand booleans since those are also common place, but that is yet to be seen since I cant take an explicit look at the source code for dartlang. I did however manage to look at the source code for it and narrowed it down. writeComponent points to _Uri._uriEncode but when looking at that function, there is no code as much as just a definition.
HTH.
Reading this post (see: 3 How to use a single definition when...) about describing a REST API using OpenAPI (Swagger) specification you can note how to keep a single resource representation for adding/updating and getting resource using readOnly property instead of having one representation for getting (GET a collection item) and other one for adding (POST to a collection). For example, in the following User single representation, the id is a read-only property which mean that it won't be sent in the representation when a user is created, it will be there when a user is retrieved.
"User":
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"readOnly": true
},
"company_data": {
"type": "object",
"properties": {
.
.
.
},
"readOnly": false
}
}
}
It is really clean and nice to keep the list of resource representation as short as possible so I want to keep the single resource representation approach but the problem I am facing to do that is: how to manage required when a property is mandatory for input only? Suppose I need to set company_data as required when the user is created (POST /users/) but non-required when an user is retrieved (GET /users/{user_id}). There are any way in OpenAPI specification to satisfy this need without lost the single resource representation?
From the Swagger-OpenAPI 2.0 spec, readonly is defined as follows:
Declares the property as "read only". This means that it MAY be sent
as part of a response but MUST NOT be sent as part of the request.
Properties marked as readOnly being true SHOULD NOT be in the required
list of the defined schema. Default value is false.
Since the specification says that a read-only property should not be required, there are no defined semantics for what readonly + required should mean.
(It might have been reasonable to say that readonly + required means it's required in the response, but still excluded from the request. In fact there is an open issue to make this change, and it looks like it's under consideration for OpenAPI 3.0.)
Unfortunately there is no way for a single schema to make properties required in the request, but optional (or disallowed) in the response.
(Again, there's an open issue proposing a "write-only" modifier, possibly under consideration for the next release.)
For now, you would need to create different schemas for these different cases. As described here, you might be able to make these schemas a bit more DRY using allOf composition.
I want to obtain a single value from a web service in JSON, just a file name i.e. "picture.png"; based on some parameters passed.
Can IOS (I guess NSJSONSerialization JSONObjectWithData:) handle this single value in JSON or on the server side should I have it send a dictionary key as in {"pic": "picture.gif"}
If there is no picture, I am returning "nopic" so again should I have it return "error" or {"error": "nopic"}
I gather the various JSON specifications are conflicting on this point so my interest is just practical...how best to handle this case.
Thanks for any guidance on this
My web application makes a REST call. If the call is successful, it will return a 'weather' json object. If the call fails, it will return a json error object.
I want to make a class that parses the resulting JSON and returns a Weather object if the call succeeded and an Error Object if the call failed.
I'm thinking of using the Factory pattern but I'm not sure if that's a good approach because the two objects are very different from one another. What is a good way to design this code?
A common approach I use is to have Weather and Error both be Response objects and have a ResponseFactory create them.
I strongly encourage you to use proper HTTP codes when designing your service as they give a more general view of the state and success of each call.
You need first to check the result of the call, and then make a decision on how to handle it, with the possibility of handling all error codes with an error callback that returns an Error JSON object, and a success callback to return a Weather JSON object. You can use the HTTP codes to create a proper response and further subdivide the logic to return more specific errors, if needed.
The use of a Factory pattern seems overkill, specially given that the objects don't relate to each other.
It really depends on the environment you'll be using your API.
As a rule of thumb, rely on the HTTP code - if you get a 404 or a 500 of course you can't come up with a parsed response.
Format your error responses in a consistent way, e.g.
404 { "message" : "Resource not found" }
400 { "message" : "Wrong parameters given" }
So you know how to parse them.
If you get a 200 OKyou know everything was right, and you can parse your response with no problem at all.
Does the Content-Type header vary depending on the type of response?
As some have noted in their answers, the HTTP status code should be used to determine "Was there an error", but just as important is the interpretation of the content type returned.
Hoping the Content-Type header does vary, I would suggest using a registry of parsers, registered by content-type they handle, and then delegate to them to handle understanding how to convert a particular content type into the object you want. In Ruby, since you didn't specify a particular language:
case response.status:
when 200..299
return parsers[response.content_type].parse(response.body)
when 400..499
raise parsers[response.content_type].parse(response.body)
else
raise "Unhandled response status"
Doing so separates the two concerns:
Determining if there was an error
Parsing of content types into classes/types in your application.