I'm using the springfox-boot-starter (3.0.0) with a REST controller that has two queries with endpoints distinguished only by request parameter e.g.
GET /foo?bar=y
GET /foo?nobar=x
I'm creating a Docket with DocumentationType.OAS_30 (or SWAGGER_2 - it doesn't seem to make any difference) and inspecting my API at the usual /swagger_ui URL.
Unless I add the "incubated" feature enableUrlTemplating(true) to my Docket I don't get to see both endpoints based on foo in the UI. I get one and only one of them.
But with that feature turned on, although I know see both endpoints, neither of them formulate the right URL when I exercise the endpoint; I get things like:
http://localhost:8080/foo{?bar%7D=&bar=111
which return a 404 because my controller presumably can't understand them.
I've found numerous discussions and issues on this, some of which mention use of an extra rfc6570 dependency to cure the problem, but the docs seem to indicate this is no longer supported, advising to turn enableUrlTemplating off.
Can someone advise me as to what is the correct approach to support for such endpoints?
Related
I’m in the middle of making an Express app. It’s just a learning project.
I’m getting some info from an Anime api called jikan.me, it provides info about different Anime series like a picture url and synopsis.
For example one is at https://api.jikan.me/anime/16 .
Now, the jikan api might have a json endpoint at anime/1 but there's nothing at anime/2.
I want to find a list of all the numbers (https://api.jikan.me/anime/[numbers]) that actually contain endpoints.
I've tried simply going to https://api.jikan.me/anime but it returns error: No ID/Path Given.
I'm expecting there is likely no absolute answer to this problem but that I might learn something about server-side code along the way.
Where would I begin to look to find this info?
This is a bit late but, Jikan is an unofficial REST API for MyAnimeList. The IDs are respective to the IDs on MAL. For example; https://myanimelist.net/anime/1 can be parsed through https://api.jikan.moe/anime/1 but the ID 2 does not exist on MAL. It's a 404, hence that error.
To initially get some IDs, you can try the search endpoint.
Furthermore, I'll be releasing REST 2.2 quite soon (this month) which will give you the ability to parse from pages like these and thus you'll get another endpoint that provides a handful of IDs to get their data from.
Source: I'm the developer of Jikan
If it's not in the documentation it's probably information not available to you... a REST api needs to be specifically configured to offer certain endpoints, that number at the end might just be an ID that's searched for in an internal database and there's no way for the application to know if there's gonna be something there; all they can do is return an error message for you to handle as is the case here.
I'm working in an app that makes many Ajax calls and results in a huge Network log in the Chrome inspector. I know that there are ways to query by things like mime-type, but I'm looking for a more fully-featured query capability.
For example, I'd like to be able to only see the pub/sub polling calls with a query like:
request_url:match(/pubnub.com/)
Or just see the GETs with:
request_method:GET
Is there a tool that makes queries like this possible?
You have a several options available. There are various pre-defined filter modes, as mentioned in the Network Analysis Reference (as you referenced in your question).
You can use the method filter with method:GET or method:POST in the input to only show requests of a particular method type. If you place a - beforehand, the filter will negate, e.g. -method:GET, will show all requests other than ones that are GETs.
There's also a filter type called domain, which is useful for only showing requests that match a particular domain. The options are limited though:
domain:stackoverflow.com would show all requests for the StackOverflow domain.
domain:*.google.co.uk would show all requests that are sub-domains
of Google UK.
Filtering request path (Method 1)
There's a better approach to filtering particular request paths. You can simply put pubnub.com in the filter input and it will match exactly what you put. You can also negate it with - beforehand, so entering -pubnub.com will show all requests that don't contain that in the path.
Filtering request path (Method 2)
You can also use Regex in the filter input, but not for the special filter modes (e.g. method, domain, etc.). So, in your case you could also use /pubnub.com/ as you filter. You can do more complex regular expressions, for instance, using /^((?!pubnub.com).)*$/ would do the equivalent of -pubnub.com via negative lookahead.
The reason I highlight Method 2 is because I fixed the feature a while ago in DevTools, as a result of another similar question that ended up being a bug in Method 1. Both bugs are completely fixed now though. See this for history of the problem if you're interested.
I am trying to work with a service that its creators describe as "restful"
To make a request to this service I have to post some Json e.g.
{
"#type" : "Something"
"$value" : 1
}
This is posted to a URL similar to this;
https://someSite.com/api/query/execute
No matter what the nature of the request, whether I am retrieving info, adding or updating it I must always use this URL (along with some header values to verify my credentials). The effects of posting to this service are determined by the JSON I send.
Depending on the nature of the call I will receive some JSON very similar to the sample above. This JSON never includes another URL (or part of one). It is always a "data object" i.e. a set of properties and their values. Sometimes I receive an empty response but know that the request has had an effect because I can view those effects through a website provided by the service provider
I have particular issues with ENUM values that I must send because I have no idea of the allowed values (they are always passed as strings)
No documentation has been provided for this service.
I am relatively new to RESTful services and JSON and would like to know whether this is truly a restful service, and if not why not?
Due to my lack of experience in this area I may have omitted some important information that would be required to properly answer this question. I will watch the comments closely and try to provide any additional clarification requested
know whether this is truly a restful service, and if not why not?
It isn't.
One of the main principles of REST is that "things" are identified by URLs. Having a single URL for all interaction with the API violates that principle.
after years of absence from web programming I now start to write a new web application from scratch. I learned the ropes of REST and found some helfful presentations and webinars about good and bad "URI styles". But all these tutorials seems to assume that there are only ressources that can be mapped to entitities that persist in a database. If one needs to GET a HTML (user-friendly) version of something, then the prevalent answer is to use content negiotation via HTTP header fields. The ultimate goal seems to have only URIs that follow the REST paradigm.
But what is the "correct" way to display web pages that cannot be mapped to an entity but are required anyway?
Perhaps I make an example to clarify what I mean. Assume we have a collection Persons and the entity Person.
Then we have
POST /Persons/ to create a new person in the collection
DELETE /Person/{id}/ to delete the person
PUT /Person/{id}/ to modifiy the person (yes, I know it can also mean to create one)
GET /Persons/ to get the list of all persons
GET /Person/{id}/ to get an individual person
and so on
With respect to the GET operations I generally found the advice to use the Accept and X-Requested-With header fields of the request to create a response that either returns the "bare" person object in a computer-readable respresentation (i.e. JSON, XML, etc.) or that returns a fully-fledged web page for a browser.
But what is about the PUT operation. Ultimately, this operation will send a bare person object (i.e. JSON, XLM) that is going to be created, but before this step I need to collect the data from the user. This means I need some empty web form that is just "eye-candy" for the human user. Of course, I could habe something like GET /newPersonForm/ but it seems that this contradict the REST philosophy, because /newPersonForm/ is an URI that only points to some user interface element.
At the moment I see to options:
Use the same name space for both kind of URIs:
POST /Persons/ --> REST api
DELETE /Person/{id}/ --> REST api
PUT /Persons/{id}/ --> REST api
GET /Persons/ --> REST api or UI (after content negiotation)
GET /Person/{id}/ --> REST api or UI (after content negiotation)
GET /Person/creationForm --> non-REST, pure UI
GET /aboutus --> non-REST, pure UI, additional company information
Make separate name spaces:
/api/... --> contains everything for REST
/ui/... --> contains html web pages
With the first approach I feel that it is somebit "unclean". Although the second approach seems cleaner, I see two problems. Firstly, if one follows this approach cleanly, one gets much double URIs, because one dispense with content negiotation and has an UI web page for every REST function. I have GET /api/Person/{id}/ to return a JSON object and GET /ui/Person/{id} to return a browser version. Secondly, I feel that this approach contradict REST philosophy because search egines and web crawlers cannot understand the structure of the site.
Any recommendations what the best practice is?
First of all, let's get a few misconceptions out of the way.
Anything for which you have semantics identifiable by an URI is a resource.
The HTTP methods don't map to CRUD operations like that. Read this answer for more on that. I recommend you read it before continuing reading this answer. This one is probably going to be helpful too.
There's no such thing as an URI that follows the REST paradigm. The only constraints REST imposes on URIs is that they must identify one and only one resource, and they must be treated as atomic identifiers. The semantics of the URI is irrelevant, although obviously you should design URIs that make sense for the developers and users.
As you already figured out, the correct way to return an user-friendly representation of something is through negotiation via the Accept header. It doesn't matter if it's not something that maps to a database. That's an implementation detail only the server knows, and that's what REST is about. When you retrieve something from a REST API, it doesn't matter if it's coming from the application server, from a cache somewhere, from a static file served by Amazon S3, or even an FTP link. The client should simply follow links, like when you click a link on a webpage and you don't care where the result comes from.
Both options you present are valid, but that has nothing to do with REST. Separating them in api and ui is a nice way to organize things for you, but what really matters to REST is how the client obtains those links. If they are implementing clients by reading those URIs in documentation and filling up values, that's not REST.
Think about it from a web browsing perspective. How do you reach that /newPersonForm html page? You followed a link somewhere else that had a label telling you to click on it to create a new Person. If you are the one clicking, it doesn't matter if it's /newPersonForm or /forms/newperson or simply /persons. REST works in the exact same way.
Even if I offer alternatives to PUT and DELETE (c.f. "Low REST"), how can I provide user-friendly form validation for users who access my web service from the browser, while still exposing RESTful URIs? The form validation problem (described below) is my current quandry, but the broader question I want to ask is: if I go down the path of trying to provide both a RESTful public interface and a non-javascript HTML interface, is it going to make life easier or harder? Do they play together at all?
In theory, it should be merely a matter of varying the output format. A machine can query the URL "/people", and get a list of people in XML. A human user can point their browser at the same URL, and get a pretty HTML response instead. (I'm using the URL examples from the microformats wiki, which seem fairly reasonable).
Creating a new person resource is done with a POST request to the "/people" URL. To achieve this, the human user can first visit "/people/new", which returns a static HTML form for creating the resource. The form has method=POST and action="/people". That will work fine if the user's input is valid, but what if we do validation on the server side and discover an error? The friendly thing would be to return the form, populated with the data the user just entered, plus an error message so that they can fix the problem and resubmit. But we can't return that output directly from a POST to "/people" or it breaks our URL system, and if we redirect the user back to the "/people/new" form then there is no way to report the error and repopulate the form (unless we store the data to session state, which would be even less RESTful).
With javascript, things would be much easier. Just do the POST in the background, and if it fails then display the error at the top of the form. But I want the app to degrade gracefully when javascript support isn't available. At the moment, I'm led to conclude that a non-trivial web app cannot implement an HTML interface without javascript, and use a conventional RESTful URL scheme (such as that described on the microformats wiki). If I'm wrong, please tell me so!
Related questions on Stack Overflow (neither of which deal with form validation):
How to send HTML form RESTfully?
How do you implement resource "edit" forms in a RESTful way?
you could have the html form post directly to /people/new. If the validation fails, rerender the edit form with the appropriate information. If it succeeds, forward the user to the new URL. This would be consistent with the REST architecture as I understand it.
I saw you comment to Monis Iqbal, and I have to admit I don't know what you mean by "non-RESTful URLS". The only thing the REST architecture asks from a URL is that it be opaque, and that it be uniquely paired to a resource. REST doesn't care what it looks like, what's in it, how slashes or used, how many are used, or anything like that. The visible design of the URL is up to you and REST has no bearing.
Thanks for the responses. They have freed my mind a bit, and so in response to my own question I would like to propose an alternative set of RESTful URL conventions which actually embrace the two methods (GET and POST) of the non-AJAX world, instead of trying to work around them.
Edit: As commenters have pointed out, these "conventions" should not be part of the RESTful API itself. On the other hand, internal conventions are useful because they make the server-side implementation more consistent and hence easier for developers to understand and maintain. RESTful clients, however, should treat the URLs as opaque, and always obtain them as hyperlinks, never by constructing URLs themselves.
GET /people
return a list of all records
GET /people/new
return a form for adding a new record
POST /people/new
create a new record
(for an HTML client, return the form again if the input is invalid, otherwise redirect to the new resource)
GET /people/1
return the first record
GET /people/1/edit
return a form for editing the first record
POST /people/1/edit
update the first record
GET /people/1/delete
return a form for deleting the record
(may be simply a confirmation - are you sure you want to delete?)
POST /people/1/delete
delete the record
There is a pattern here: GET on a resource, e.g. "/people/1", returns the record itself. GET on resource+operation returns an HTML form, e.g. "/people/1/edit". POST on resource+operation actually executes the operation.
Perhaps this is not quite so elegant as using additional HTTP verbs (PUT and DELETE), but these URLs should work well with vanilla HTML forms. They should also be pretty self-explanatory to a human user...I'm a believer in the idea that "the URL is part of the UI" for users accessing the web server via a browser.
P.S. Let me explain how I would do the deletes. The "/people/1" view will have a link to "/people/1/delete", with an onclick javascript handler. With javascript enabled, the click is intercepted and a confirmation box presented to the user. If they confirm the delete, a POST is sent, deleting the record immediately. But if javascript is disabled, clicking the link will instead send a GET request, which returns a delete confirmation form from the server, and that form sends the POST to perform the delete. Thus, javascript improves the user experience (faster response), but without it the website degrades gracefully.
Why do you want to create a second "API" using XML?
Your HTML contains the data your user needs to see. HTML is relatively easy to parse. The class attribute can be used to add semantics as microformats do. Your HTML contains forms and links to be able to access all of the functionality of your application.
Why would you create another interface that delivers completely semantic free application/xml that will likely contain no hypermedia links so that you now have to hard code urls into your client, creating nasty coupling?
If you can get your application working using HTML in a web browser without needing to store session state, then you already have a RESTful API. Don't kill yourself trying to design a bunch of URLs that corresponds to someone's idea of a standard.
Here is a quote from Roy Fielding,
A REST API must not define fixed
resource names or hierarchies
I know this flies in the face of probably almost every example of REST that you have seen but that is because they are all wrong. I know I am starting to sound like a religious zealot, but it kills me to see people struggling to design RESTful API's when they are starting off on completely the wrong foot.
Listen to Breton when he says "REST doesn't care what [the url] looks like" and #Wahnfrieden will be along soon to tell you the same thing. That microformats page is horrible advice for someone trying to do REST. I'm not saying it is horrible advice for someone creating some other kind of HTTP API, just not a RESTful one.
Why not use AJAX to do the work on the client side and if javascript is disabled then design the html so that the conventional POST would work.