I use Swashbuckle (5.2.2) and Swagger to create a documentation of my WebAPI project.
I need to create a static documentation so I use swagger2markup on the json generated and this works fine.
However, I have a lot of generic types in my API for paging, for resources, etc.
Many return types looks like that: Page<Resource<MyType>>
As a result, in the documentation I get a lot (A LOT) of redundant definitions. For each Page<Resource<MyType>>, I get 3 definitions, if I have 10 types, I get 30 definitions (instead of 13), if I have 100 types, I get 300 definitions (instead of 103).
Is there a way to reduce this excess of information gracefully ?
Related
I would like to find if there is a solution that helps with finding the differences between two different API versions of the same product(Swagger/Open API 2.0). For example, this tool : https://github.com/Sayi/swagger-diff compares parameters, responses, notes, http method(GET,POST,PUT,DELETE...), but doesn't compare definitions, which is the main thing I need currently.
Thanks in advance!
Maybe try https://www.npmjs.com/package/swagger-diff instead. It includes definitions, but the output is less refined, if I remember correctly.
I am building a REST API that uses a filter parameter to control search results. E.g., one could search for a user by calling:
GET /users/?filter=name%3Dfoo
Now, my API should allow many different filter operators. Numeric operators such as equals, greater than, less than, string operators like contains, begins with or ends with and date operators such as year of or timediff. Moreover, AND and OR combinations should be possible.
Basically, I want to support a subset of the underlying MySQL database operators.
I found a lot of different implementations (two good examples are Google Analytics and LongJump) that seem to use custom syntax.
Looking at my requirements, I would probably design a custom syntax pretty similiar to the MySQL operator syntax.
However, I was wondering if there are any best practices established that I should follow and whether I should consider anything else. Thanks!
You need an already existing query language, don't try to reinvent the wheel! By REST this is complicated and not fully solved issue. There are some REST constraints your application must fulfill:
uniform interface / hypermedia as the engine of application state:
You have to send hypermedia responses to your clients, and they have to follow the hyperlinks given in those responses, instead of building the requests on their own. So you can decouple the clients from the structure of the URI.
uniform interface / self-descriptive messages:
You have to send messages annotated with semantics. So you can decouple the clients from the data structure. The best solution to do this is RDF with for example open linked data vocabs. If you don't want to use RDF, then the second best solution to use a vendor specific MIME type, so your messages will be self-descriptive, but the clients need to know how to parse your custom MIME type.
To describe simple search links, you can use URI templates, for example GET /users/{?name} will wait a name parameter in the query string. You can use the hydra:IRITemplateMapping from the hydra vocab to add semantics to the paramers like name.
Describing ad-hoc queries is a hard task. You have to describe somehow what your query can contain.
You can choose an URI query language and stick with URI templates and probably hydra annotation. There are many already existing URI query languages, like HTSQL, OData query (ppl don't like that one), etc...
You can choose an existing query language and send it in a single URI param. This can be anything you want, for example SQL, SPARQL, etc... You have to teach your client to generate that param. You can create your own vocab to describe the constraints of the actual query. If you don't need complicated things, this should not be a problem. I don't know of already existing query structure descibing vocabs, but I never looked for them...
You can choose an existing query language and send it in the body in a SEARCH request. Afaik SEARCH is not cached or supported by recent HTTP clients. It was defined by webdav. You can describe your query with the proper MIME type, and you can use the same vocab as by the previous solution.
You can use an RDF query solution, for example a SPARQL endpoint, or triple pattern fragments, etc... So your queries will contain the semantic metadata, and not your link description. By SPARQL you don't necessary need a triple data storage, you can translate the queries on server side to SQL, or whatever you use. You can probably use SPIN to describe query constraints and query templates, but that is new for me too. There might be other solutions to describe SPARQL query structures...
So to summarize if you want a real REST solution, you have to describe to your clients, how they can construct the queries and what parameters, logical operators they can use. Without query descriptions they won't be able to generate for example a HTML form for the user. If you don't want a REST solution, then pick a query language write a builder on the client, write a parser on the server and that's all.
The Open Data Protocol (OData)
You can check BreezeJs too and see how this protocol it's implemented for node.js + mongodb with breeze-mongodb module and for a .NET project using Web API and EntityFramework with Breeze.ContextProvider dll.
By embracing a set of common, accepted delimiters, equality comparison can be implemented in
straight-forward fashion. Setting the value of the filter query-string parameter to a string using those
delimiters creates a list of name/value pairs which can be parsed easily on the server-side and utilized
to enhance database queries as needed. You can use the delimeters of your choice say (“|”) to separate individual filter phrases for OR and ("&") to separate
individual filter phrases for AND and a double colon (“::”) to separate the names and values.
This provides a unique-enough set of delimiters to support the majority of use cases and creates a user readable
query-string parameter. A simple example will serve to clarify the technique. Suppose we want
to request users with the name “Todd” who live in "Denver" and have the title of “Grand Poobah”.
The request URI, complete with query-string might look like this:
GET http://www.example.com/users?filter="name::todd&city::denver&title::grand poobah”
The delimiter of the double colon (“::”) separates the property name from the comparison value,
enabling the comparison value to contain spaces—making it easier to parse the delimiter from the value
on the server.
Note that the property names in the name/value pairs match the name of the properties that would be
returned by the service in the payload.
Case sensitivity is certainly up for debate on a case-by-case basis, but in general,
filtering works best when case is ignored. You can also offer wild-cards as needed using the asterisk
(“*”) as the value portion of the name/value pair.
For queries that require more-than simple equality or wild-card comparisons, introduction of operators
is necessary. In this case, the operators themselves should be part of the value and parsed on the server
side, rather than part of the property name. When complex query-language-style functionality is
needed, consider introducing query concept from the Open Data Protocol (OData) Filter System Query
Option specification (http://www.odata.org/documentation/odata-version-4-0/)
There seems to be a lot of standards (like OData), but many are quite complicated in that they introduce new syntax.
For simple multi filtering the following format avoid polluting the parameter namespace while still standing on top of existing web-technology
GET /users?filter[name]=John&filter[title]=Manager
It's easily readable and on the backend languages like PHP will receive it as an array of filters to apply.
A possible standard would SCIM which is adopted by some commercial products. But it's not distinguished by brevity. For a pet project I used this
= equal
! not equal
* like
< smaller
> greater
& bitwise and
| bitwise or
^ bitwise xor
~ in comma separated value list
Examples
So GET /user?name=*An* would get all users whose name start with An and GET /user?name=~Anna,Bertha would get those two users.
Not yet a standard but who knows...
I am quite new to Core Data, and I'm trying to implement it into my relatively simple OS X application. My application takes some file URLs provided by the user, gets some more information about the files (like creation date, for example), and then stores the URLs for use later.
I am wanting to have those file URLs, and related data, stored in a 'central' location so I can access, modify, and change the order of them (order is really important) from any of the classes in my application (correct me if I'm wrong, but I think Core Data is ideal for this).
I have my Core Data Model setup in Xcode (it only has one Entity which has a couple of Attributes), I've create an NSManagedObject Subclass to match the Entity in the Model, and I'm using Bindings to tie the data to a TableView. However, like I said, I need to be able get at this data from any class in my application. I have been reading Apple's Documentation and a book with a section on Core Data, however I am both struggling to get my head around it, and am yet to come across a section that describes the needs I mentioned above.
Any help with this (even just a link to a useful article) would be very much appreciated.
Thanks in advance.
I currently have an API endpoint which returns an array of objects each containing 4 variables in JSON format.
The size of the data ranges from 500kb to 5mb - depending on the number of records. In order to reduce the size of the return, we're considering removing the labels from the objects, and returning an array of arrays.
E.g.
[{propertyone:123,propertytwo:456,propertythree:789,propertyfour:012},etc,etc,etc]
would become
[[123,456,789,012],etc,etc,etc]
We would then document that array position 0 is to considered propertyone, etc. There may be a point in the future when this API becomes public. Is it considered better practice to leave the names in, or would serving a documented API with an enforced order suffice.
Well documented APIs are often the best APIs. Having external documentation for your API is important, but the data you return needs to be documented as well, and nothing beats self-documenting data.
I think by removing the property names, you're going to lose this self-documenting entirely and you could end up limiting yourself in the future as well. For example, consider only wanting to return partial data, how would you represent it without those property names?
In addition to the documentation, if you're returning JSON then depending on the consumer's environment, providing those properties could give them a natural model to work with. Consider JavaScript as an example, if they simply parse your response into JavaScript objects they essentially have a client-side model implemented for free and that will make it a joy to work with your API.
Nonetheless, speed is important and I would suggest looking into different measures for reducing the size of the return. Often a common solution to this is providing paged results, requiring a client to perform additional requests if they desire more data. Also, depending on the shape of your data, you could benefit greatly by using something as simple as GZIP compression on your responses.
While designing an API, as long as you document it and it works as described, normally anything will suffice. However, the API that empowers the consumer is the one that succeeds.
I'm designing a REST API and have run across this issue:
How should a set of values be defined?
Say I have a Picture object that is going to be requested at http://myserver.com/api/getPicture/1
so the server responds:
{
url : "http://myserver.com/pictures/1.jpg",
taken_at : "1/1/2012"
}
Now, say I wanted to add a color_depth field.
Two possible choices to do this are:
color_depth : "BLACK_WHITE" or "COLOR" or "GRAYSCALE"
color_depth : "0" OR "1" OR "2" //would need to map these to their meaning somewhere
Is there a standard for what to do in this situation?
For JSON, there isn't any de-facto or official standard. JSON-SCHEMA tries to solve this, but the specs aren't recommended yet and even implementations aren't popular.
Using XML, XML Schema is the standard solution. For RDF, there is also RDFS that solves this problem.
For every format, the coice is yours. Depending on integer identifiers (1, 2, 3) and translating them without a schema means that your requests are far less self-contained than strings that express what they mean like "COLOR". It is a core concept of RESTful API design that requests should be self-contained. This loosely relates to the visibility property of RESTful architectures described in the Roy Fielding dissertation.
I would go for full strings.