I am using Rest Doc to document my Rest APIs. Based on the TestNg methods I generate the snippets that, later on, I use in the asciidoc.
For example, I have a rest endpoint to retrieve people, and also the TestNg method to document it. So then, I can use it in my ascii doc like this:
=== Get People
Get the people registered.
operation::get-people[snippets='http-request,request-fields,http-response,response-fields,error-codes']
But now, my API changed, and I introduced versioning, so the API is different from version 1 to version 2. I also want to document that properly, but I don't know how to do it by being the "less intrusive" possible.
I would like my documentation to have this structure
Resources
v1
getPeople
v2
getPeople
For the API that really change from one version to another I need to generate a different snippet per version the api support, since maybe the request fields or response fields are different.
But, I also have some other rest endpoints that has the same API from one version to another, and I think that I also need to generate the snippets for each version since the version is part of the rest endpoint path.
Do you have any idea on how to being able to add versioning to the rest docs?
Related
I am using Swagger for REST API documentation which is built using Spring Framework. I am looking for better alternatives where I don't need to define complex resources again and again in every API.
Like Google has a well-defined documentation Google Doc. What frameworks top IT companies using for it.
Well I have advised two of those companies to use OPTIONS.
OPTIONS data can be cached at runtime giving a custom APIDOC per each ROLE/AUTHORITY.
That way USER will not see ADMIN endpoints and you can create a dynamic APIDOC.
In an HTTP-driven microservices architecture, each service might have a number of public endpoints that return JSON, for example, to a client or an API gateway intermediary. These services could also accept POSTs with JSON bodies of a certain shape, or query strings of a certain shape, etc.
What are some good options for documenting or programmatically keeping track of these "contracts" between services? I.e, if service A's /getThing endpoint has been refactored to return different data, is there a documentation tool or methodology that would facilitate updating the API gateway to adapt to this change?
For programmatically management of contracts, if you using spring-cloud stack then you must look into spring-cloud-contract, by which you can easily keep track of your latest version of contracts for your Rest endpoints and also if any change occurs in your api endpoint, this will help you notify by breaking the contract and failing the test-cases build around it.
Let's say for example, service A's /getThing endpoint has been refactored to return different data then all calling services to this endpoint will fail while build time of your project.
However, this methodology won't facilitate updating the API gateway to adapt to this change as there might different logic you want to perform of every new version of your endpoints.
You can also create Rest Docs snippets using these endpoint contracts. checkout Rest Docs snippets. You can also use swagger for documenting your endpoints.
for NodeJs check here.
Is there a standard out-of-the-box way to access an API using GET or POST in TypeScript?
I only find libaries that do that like fetch or superagent suggested here when using React or HttpClient suggested here when using React.
I wonder though if there is a plain an simple way from within TypeScript to consume a REST API.
I wonder though if there is a plain an simple way from within TypeScript to consume a REST API.
Lets simplify REST API to be *I want to make GET and POST requests. The fact that it is a REST style API is not relevant.
I want to make GET and POST requests
Native ways of doing this depends on the JavaScript environment. e.g. Browser's traditional API has been XMLHttpRqeuest : https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest which is fully supported by TypeScript. A newer API is fetch which is also supported by TypeScript but might not be supported by the browser you are targetting.
On node you would use http module https://nodejs.org/api/http.html
Suggestion
Now if you want an API that works across both node and old browsers you will need some library that abstracts the native features. One suggestion is axios which works with TypeScript out of the box.
I am trying to implement HATEOS based REST service for hotel booking but have this confusion:
1) How does apart from WADL, the client comes to know about possible operations and their corresponding URI. Should I put all possible operations and URI as response when the client hits the root of REST service?
2) When the client gets a list of all accommodation options in an area, I am returning a list of all hotels in the area he asked about. The response contains:
<accommodation>
<hotel info="http://welco.me/hotel/xxxxxx" price="5000"/>
<hotel info="http://welco.me/hotel/yyyyyyy" price="3000"/>
</accommodation>
But the query I have here is how the client is going to know about other related possible operations like getting the list in sorted order of price?
In answer to your first question, there are a couple of specs for documents that allow clients to discover RESTful APIs.
Swagger
JSON Home
Google use their own Discovery Service, however unlike Swagger and JSON Home, unfortunately I don't think there are open sourced libraries that help you use expose it for your own APIs.
For Your second questions again, I would tend towards clients/developers discovering parameters such as sorting from the Swagger/JSON Home document. However if it is a super strong/important relationship you could also return it in the responses as linked data:
In HAL you can provide a links object with links to related resources.
In JSON-LD you can add a field with a value of the related API url. You may then add an #content to add information describes what that relationship means.
You should use link hints. An older way of doing this, the OPTIONS method, has some longstanding caveats.
Include links that use a custom link relation something like http://welco.me/#sort-by-price where you define the URI to mean whatever you want it to. You should provide some developer documentation at that URI but the client app will never dereference it, it merely uses the URI as an opaque string for equality comparisons.
I am currently working on a REST service. This service has an entity which has different versions, similar to Wikipedia articles.
Now I'm wondering what I should return if for
GET /article/4711
Should I use a (temporary) redirect to the current version, e.g.
GET /article/4711/version/7
Or should I return the current version directly? Using redirects would considerably simplify HTTP caching (using Last-Modified) but has the disadvantages a redirect has (extra request, 'harder' to implement). Therefore I'm not sure whether this is good practice though.
Any suggestions, advise, or experiences to share?
(btw: ever tried search for "REST Version"? Everything you get is about the version of the API rather than entities. So please bear with me if this is a duplicate.)
If you treat versions as entities (which by the looks of it you do) this is what I'd suggest:
GET /article/4711
returns a list of all versions (and links to them). Which makes /article/4711 a container entity.
GET /article/4711/latest
returns contents of the latest version. You might want to consider /version/latest to get in-line with the below.
GET /article/4711/version/7
returns the specific version of the article.
Depends on your intended behavior for GET /article/4711. If it is intended to always point to the latest version, then it should return the latest version directly. Redirecting to a particular version seems problematic as you are relying on the user/client library to not visit that particular URL in the future. To translate into HTML terms, a user might bookmark the version/7 URL and be surprised that they are now accessing an older version instead of the up to date version they originally typed into the address bar.
You might want to look at https://datatracker.ietf.org/doc/html/draft-brown-versioning-link-relations .
Using the CMIS link relations and the HTTP Link header you can make /article/4711 the latest and provide a link to the versions, e.g. Link: </article/4711/versions>;rel=version-history
Article versions and hypertext
If you're really concerned about making the interface RESTful then you should consider how to do this in a HATEOS style.
In my opinion that would mean returning enough information that the user is able to navigate through the list of revisions of your entity. If you read this from Roy ...
"The interface doesn’t need to be discovered. It is defined right there in the hypertext. The representation tells the client how to compose all transitions to the next application state"
... you'll get a feel for how your GET /article/4711 should return enough information to
Get the latest version of the article
Get the next/previous versions
You'll know what works best for your model but as a pointer you could consider using tags
<link rel="older"
type="text/html"
href="http://www.yourdomain.com/article/4711?version=6"/>
...
I think it would be more restful to return a list of the revisions for:
GET /article/4711
You could also have:
GET /article/4711/current
Which returns the current version directly.