I have a question about format of API REST
I have different API :
GET /api/payment/providers
GET /api/payment/recipients
GET /api/payment/rules
DELETE /api/payment/rules/{uuid}
PUT /api/payment/rules/{uuid}
POST /api/payment/rules
Is this format correct?
Or should I have something like that :
GET /api/paymentProviders
GET /api/paymentRecipients
GET /api/paymentRules
DELETE /api/paymentRules/{uuid}
PUT /api/paymentRules/{uuid}
POST /api/paymentRules
I heard that REST must respect this format:
Resource list / specific resource / sub-resource list / specific sub-resource / etc...
But, my format is correct or no?
Thanks!
TL;DR: your resource identifiers are fine as is.
I heard that REST must respect this format:
No.
You can use any spelling conventions you like for your resource identifiers.
RFC 3986 defines the production rules for URI, and HTTP Semantics defines a more restricted set of rules to follow when using the http/https URI scheme.
But neither of these put any semantic restrictions on the use of path segments.
Resource identifiers are similar to variable names - the machines don't care what spellings you use, so you can choose any spelling you like. The best spellings to use are those that are most convenient for the people you care most about.
Related
I'm drawing my API routes.
A user has projects, projects have actors, actors have addresses.
There is no address without an actor, there is no actor without a project, and there is no project without a user.
Would this be the correct way to build the end_point?
GET /users/{user_id}/projects/{project_id}/actors/{actor_id}/addresses
There is no such thing as a REST endpoint. There are resources. -- Fielding, 2018
What you seem to be asking about here is how to design the identifier for your resource.
REST doesn't care what spelling conventions you use for your resource identifiers, so long as they satisfy the production rules described by RFC 3986.
Identifiers that load data into the query part are convenient if you are expecting to leverage HTML forms:
GET /addresses?user={user_id}&project={project_id}&actor=actor_id
But that design is not particularly convenient if you are expecting to use dot segments to reference other resources.
Choosing some alternative that is described by a URI Template will make some things easier down the road.
/users/{user_id}/projects/{project_id}/actors/{actor_id}/addresses
That's fine. Other spellings would also be fine (hint: URL shorteners work).
Broadly, you choose identifier spellings by thinking about the different contexts in which a human being has to look at the URI (documentation for your API, browser histories, access logs, etc.) and choose a spelling that works well in at least one of those settings.
This question has been asked before... here -> what are the URLs for in claim-types.
But the accepted answer doesn't actually answer the question. Why are claim types in ASP.NET Core Authentication formatted as HTTP Urls? What is the purpose of the "http://schemas.microsoft.com/...." portion of the claim type? It's not an actual hyper text transfer protocol URL to a web site or a web service of some kind. There is no schema document sitting at that address. So what is the purpose of formatting them as HTTP URLs? I know WHAT they are. I just don't know WHY they are formatted as they are.
I believe Microsoft use URIs because they suit the purpose - they need a unique identifier to identify each claim type, that is preferably human-readable, and guaranteed not to accidentally clash with names created by other third-party components or developers themselves.
The fact that Microsoft chose URLs (which is just a type of URI) is probably conventional. Over the years various standards for claim types were developed by different organizations, many of which were based on XML namespaces that were URLs (for example, see this standard document by OASIS). Many of these well-known claim types are still in use today, so it would make sense to format any newly-defined claim types in the same fashion as the existing well-known ones.
For example, when you perform an call from summary api of wikipedia, there is this header in the request
accept:application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.3.7"
What is the purpose of this particular bit. I would like to understand since the value changes when you, for example, use the VisualEditor or access the api with different mean.
profile="https://www.mediawiki.org/wiki/Specs/Summary/1.3.7"
This specifies the response format and provides convenient access to a human-readable documentation.
The URL in your header leads to nowhere, but https://www.mediawiki.org/wiki/Specs/Summary/1.3.0 does exist and is probably valid for 1.3.7 as well.
There is a gazillion of questions about RESTful interface naming conventions, esp. around singular vs plural resource names. A somewhat convention is:
GET /users Retrieve collection of users
GET /users/{id} Retrieve user
POST /users Create user
PUT /users/{id} Update user
DELETE /users/{id} Delete user
However, the above does not work when resource is a value derived from the environment.
My hypothetical application has the following endpoint:
GET /source Get information about the source of the query.
That responds with:
Referrer URL
Remote IP
Since source is derived from the environment, there is never more than one source, therefore calling the resource sources or providing sources/{foo} lookup is not practical.
Does REST style propose how to handle naming of these entities?
Dr. Fielding notes in section 6.2.1 of his famous dissertation :
..authors need an identifier that closely matches the semantics they
intend by a hypermedia reference, allowing the reference to remain
static even though the result of accessing that reference may change
over time.
Therefore, it makes sense to use plain source endpoint.
It would be a different thing if you wanted to provide more general service around IP address provided, like this one.
Is it true that to implement a RESTful API, one has to implement a URL structure that looks like this
http://example.com/post/
http://example.com/post/123
where the /123 would be used for edit, delete
Another way to ask the question is: can a URL that looks like this be called RESTful?
http://example.com/script.php?method=get_title&blogid=123
You don't have to design your URI structure like that. It could also be /some_obscure_string/base64_encoded_title/unique_id. This could also be RESTful, depending on several other factors.
But there are several best practices on how to design URIs in a RESTful web application and being as simple and as human readable as possible is one of them.
Your example http://example.com/script.php?method=get_title&blogid=123 could also be RESTful, but the query parameters indicate that some kind of RPC- or RMI-over-HTTP is used instead.
To sum it up: Don't put too much thought into your URI design. This will come automatically with a good and proper RESTful design of your application.
The Idea behind REST is that every resource has it’s own URL and you use the different HTTP methods to interact with those resources. It makes sense to define the URL structure so that the hierarchy between different resources is reflected in the URL, but you don’t have to.
If you have URLs like this
/all-posts/
/first-post
/some-stuff/second-post
/third-post
you still could provide an RESTful API to this. The Idea is that a GET to /all-posts/ returns a list of the URLs of every post object and the client uses those URLs to interact with the resources. Basically the URLs should be treated as opaque data by the client.
As long as the URL that is embedded in the client doesn’t change you also could change the structure without having to change the client.
Your example URL probably doesn’t belong to a RESTful API, since it contains a method get_title. In REST a URL represents a thing. What is to be done with the thing (should it be modified, should it contents be retrieved, ...) is not part of the URL, for that REST uses the different HTTP methods.
A key aspect of REST is that the url is the resource. a uri like
http://example.com/script.php?etc-etc-etc
doesn't put the resource identifier in the resource portion of the uri. that's not to say that a RESTful API shouldn't ever use get parameters; in fact, that's just fine:
http://example.com/posts?sort=date_asc&offset=20&limit=10
might be a great way to get the URI's of the 3rd page of oldest posts. However, using get parameters in this way should only be used in requests where the method is also GET. PUT and especially POST methods should really use simple uri's with the resource that will be affected in only the path portion.
RESTful URI design is all about resources access and they should be structured in the RESTful manner, so you should not have any query strings.
e.g. of GET
authors/
authors/1
authors/1/books
authors/1/books/10
authors/1/books/10/summary
etc.
Anything and everything is called RESTfull these days, just look at some of the responses by it's inventor Dr Roy Fielding and you'll get some ideas. It is worth doing some reading on the subject.
P.S you do not need post,get etc in your URIs, HTTP protocol is at present mostly used for consuming REST APIs and you can pass verb as a part of the call. Also there is a concept of content negotiation i.e you can request any available format from REST API (json,xml atc).
The REST concept is really based on the fact that it is URL driven, and not driven by large data-blobs. With REST, you don't have to pass a giant soap request to invoke a method - your method call/object creation/whatever you want to do is invoked simply by the URL, and the verb you used vs that URL.
Example URLs:
GET http://del.icio.us/api/
GET http://del.icio.us/api/peej/tags/
GET http://del.icio.us/api/peej/tags/test
DELETE http://del.icio.us/api/peej/bookmarks/[hash]
The structure of your URLs doesn't matter. What does matter is that each URL identifies exactly 1 resource. Each resource can have multiple URLs that point to it but each URL should only point to 1 resource.
This can be helpful. Ref:
RESTful service URLs