A resource is an object thats important enough to be referenced in itself.

Use consistent resource naming conventions and URI formatting for minimum ambiguity and maximum readability and maintainability. GET api/courses/populated?_fields=university,university.city&_sort=-university.city I dont understand the populated resource, maybe you can remove it.

No need to complicate this simple requirement. Having a consistent and robust REST resource naming strategy will prove one of the best design decisions in the long term. /jobs/job-status.

rest-apis-must-be-hypertext-driven seems like a fixed resource name to me. Client then must send the token with each subsequent request. I am curious to know why you want to count the number of layers in the URI. It would be better IMO to include a status attribute in the cart resource and update that. Very good question.

A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

It is something more of preferences.

Great article thank you, I have a question for naming of resource: There are two api in my project. PUT need not result in actual resource creation.

would not be modifiable via this method, which would lead a 4XX status code and appropriate error message. A document resource is a singular concept that is akin to an object instance or database record.

display them on map, I would like to make only one request for the whole data.

still trying to see how i can past all the /var1/var2/var3 into actual $array[0] = var1; then the part where i need to specifically do /var3?foo=bar and i would still get $_GET[foo]. For additional information, check out this REST API tutorial. Keeping verbs out of your URLs is also a good idea. Resources are fundamental to the concept of REST. I explained in the first sentence of the comment. Is moderated livestock grazing an effective countermeasure for desertification? Keeping these nouns self explanatory helps developers understand the kind of resource described from the URL, which can eventually enable them to become self sufficient while working with your API .

Servers must have the freedom to control their own namespace but still there MUST be some design at server side which will create those hypermedia links in some standard structure. When resources are named well, an API is intuitive and easy to use. When convenient, lowercase letters should be consistently preferred in URI paths. The key abstraction of information in REST is a resource.

A well- designed API also has an example of the kind of response one can expect on successful call against a URL. with my list of device-id in body, but you wrote that this URI is for create. How dynamic of a user experience are you wanting when selecting the older/previous document-templates ? I will also not recommend to use /{id} and /admin both for same API.

Every client request and server side response is a message and, in an ideal RESTful ecosystem, these messages must be self descriptive. File extensions look bad and do not add any advantage. Finally, a complete API will make it possible for developers to make full- fledged applications against the data you expose. Do you have any other suggestions? Hey, Regarding using query component to filter URI collection how should I do it if I want only managed-devices that has region field exists?

So your /check API will run the checks and submit the progress to a JMS topic. What you are looking for does exist, have a look at RDF at https://en.wikipedia.org/wiki/Resource_Description_Framework, FOAF: http://xmlns.com/foaf/spec/ and DC: https://www.dublincore.org/specifications/dublin-core/. In this blog post, I will detail a few best practices for designing RESTful APIs.

Obviously versions naming can be changed to whatever is more appropriate and I am just using it here to help communicate my point.

Some frameworks use it like https://example.com/index.php?q=/device-management/managed-dives unless you set up mod_rewrite.

Hi I want get the data by multiple params (name,age,group), http://www.mywebsite.com/my-project/data/name/age/group, I will suggest to use filters e.g.

RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb). I will suggest to append token ids using hyphen.

Should I club 5678/2345 as 5678-2345 or using any other character?

If I want to quit a team, which one if prefer DELETE /teams/{team_id}/user DELETE /teams/{team_id}/user/quit, delete a user from a team means to quit, but information seems not clear enough, 2. if I need to send some email, which is better, /users/email/send-verification /users/email/send-reset-password, /users/send-verification-email /users/email/send-reset-password-email, 1. Thanks for all this huge documentation, it is really helpful. /users/{userId}/ to get and set email.

Theres no rule on keeping the resource nouns singular or plural, though it is advisable to keep collections plural.

But the example /customers/{customerId}/accounts/{accountId} could also be written /accounts/{accountId}, given that account IDs should be unique within a bank.

Removing them decreases the length of URIs as well. Controller resources are like executable functions, with parameters and return values; inputs and outputs. If the end user successfully calls the end point with a GET method, the user should obtain the above data along with a 200 response code to validate the correct usage.

: [GET] /document-templates returns: [ {code: doc1, template: This is template of doc1 ${code}, validFrom: 2020-07-10T15:00:00, validTo: 2021-07-10T15:00:00}, {code: doc1, template: This is newer version of template of doc1 ${code}, validFrom: 2021-07-10T15:00:01, validTo: null} ]. A successful method used against your resource should return a 200-type response. One workaround for this seems to be changing around the order you list your URLs in in your backend, putting the catch-all URL looking for a variable last.

To be RESTful, I divided the code for each of them.

If youre having second thoughts about a specific resource or collections functionality, then leave it for the next iteration.

Use plural name to denote store resource archetype. The data youre trying to expose can be characterized by a lot of properties which could be beneficial for the end consumer working with your API.

you need a middleware for protected endpoints to check a users entitlements for each end point. The resource archetypes dont seem to clarify the differences between a collection and a store enough.

As the last character within a URIs path, a forward slash (/) adds no semantic value and may confuse. 2) accountIds in both URIs can be different numbers.

https://twitter.com/fielding/status/1052976631374000128.

A good rule of thumb is to help developers understand exactly what a successful response would give them in under five seconds. When we can add and remove items from the cart, but actual items in the system do not change.

Im curious to find out what you think about designing the user authentication aspects of an application.

If you need to keep the /, just replace it with something else for your request, as Admin suggested, and then when you retrieve it, parse it and replace that other symbol with / again. In general, all this talk of URI names is no more than REST buzzwording.

Having /users/{username} and /users/{user-id} wouldnt seem too illogical though (but on the other hand: whats the purpose?). For example, if we have users that can post, DELETE/user/3/post/5 should only occur if current user (via token) = owner (i.e.

This is a problem Ive run into before, and is actually what I was researching when I came across this post As soon as you allow resources/{variable}, you can no longer put any controller verbs or anything after /resources/ because itll get interpreted as your variable.

As for the other options it depends on what your intentions are for each as to what type of solution to use. Any thoughts on how to handle something like tiers/grades/reliability levels in the API resource naming?

Not specific region=USA, only that region exists? hyphen, underscore or hash.

Asking for help, clarification, or responding to other answers. In this case my scope would be groups:clone.

Saying it in a different way: Your API needs to be able to authorize the user to perform the task.

Often, you will encounter requirements where you will need a collection of resources sorted, filtered, or limited based on some specific resource attribute.

Above you wrote, URIs should only be used to uniquely identify the resources and not any action upon them, but I thought this might be an exception to that rule. I was looking at the usage of .htaccess. A well- designed API also has an example of the kind of response one can expect on successful call against a URL.

You also want to limit the number of results to 10 per API call to prevent server load.

The above cases and relationships are important considerations in the design of the API, and can be handled using the appropriate parameters.

There could be numerous such relationships and properties, and its not good practice to define resources for each of them. If i have resource(Folder) called Customers inside this should I create controller called CustomerController or CustomersConstroller ?

I like to use this way of calling custom methods or what you call controllers.

Apart from the above reason, if you want to highlight the media type of API using file extension, then you should rely on the media type, as communicated through the Content-Type header, to determine how to process the bodys content.

It is supposed to be stateless isnt it. We use string type IDs which could include special characters like the forward slash.

In fact, in your later controller examples, you used singular nouns (cart and playlist) for store as well: http://api.example.com/cart-management/users/{id}/cart/checkout http://api.example.com/song-management/users/{id}/playlist/play. Combining everything in one API and making it complex I will not suggest that.

Let us say there is a single resource that we need to retrieve via two unique references (id or code) separately: *. Would GET api/course/populated=[university,university.city] work fine? Find out how Swagger API design tools can help.

Hi, You say elsewhere that a resource should have a single logical URI. 1) If a frontend has many packages (in sinle screen) then GET /leaderboard/{frontend}-{packagename} does not make sense to me.

The amount of data the resource exposes should also be taken into account.

Finally, when in doubt, leave it out. These are just some of the ways you could design parameters that strive towards API completion and help your end developers use your API intuitively.

A store is a client-managed resource repository. : A well designed API will be easy to work with, and its resources and associated operations can quickly be memorized by developers who work with it constantly.

The operations GET, PUT, POST and DELETE are already used to operate on your resource described by the URL, so having verbs instead of nouns in the URL can make working with your resources confusing. One of the main reasons why API design is crucial is to help the end consumer use your API.

REStful APIs comprise majorly of HTTP methods which have well defined and unique actions against any resource. Create a new group: POST https://api.myapp.com/groups, Create a new user and add him to existing group: POST https://api.myapp.com/groups/{groupId}/users, Create a new user & group: POST https://api.myapp.com/users, Add an existing user to an existing group: POST https://api.myapp.com/groups/{groupId}/users/{userId}, Get a group: GET https://api.myapp.com/groups/{groupId}, Get a user: GET https://api.myapp.com/users/{userId}. A user could have a list of accounts and a separate URI for its address as you could consider addressing a separate resource. Session history for a user can be made available at: How do you actually logout of the RESTful API? I am using this one, but i am sure there is better way to naming them.

The above cases and relationships are important considerations in the design of the API, and can be handled using the appropriate parameters.

I find it interesting that almost every API Ive developed has a couple of Document types that are reused to the point that I just copy/paste from my personal library when theyre needed. POST /jobs/{job-type} Creates an instance of a job and it gets processed by an asynchronous job handler in the backend.

There are a lot of response codes. Though, multiple ACLs can belong to single role (as sub-collection), still I see it independent resource different from Role. But how do I design the routes?

I think it is convenient to use only Post and Get. How to define the number of layers, whether the parameter in the path are counted as one layer. Any API/application interested in the status of any Job, must subscribe to the correct topic/queue e.g.

These are filtered by semester. Keeping these nouns self explanatory helps developers understand the kind of resource described from the URL, which can eventually enable them to become self sufficient while working with your API .

For example, sub-collection resource accounts of a particular customer can be identified using the URN /customers/{customerId}/accounts (in a banking domain).

I think its a bad nameWhats your opinion Sorry for my poor English, Thanks for any suggestions. There may be another practical reason to avoid trailing slashes. Increase or decrease action is not important here. I dont know if this approach is RESTful: 1- something.com/api/admins/some-resource 2- something.com/api/businesses/some-resource 3- something.com/api/users/some-resource, I would be more than happy to get some RESTful ideas, thank you .

Pick your identifier and stick with it. Let say I have a resource document-template with attributes code, template, validFrom, validTo, e.g.

Scientific writing: attributing actions to inanimate objects. Login and Logout are verbs and should not be part of the resource URI.

The base URL is the consistent part of this location.

There are resources. This should tie into the user in the backend and the server should be able to determine if the current user is an admin / business owner / typical user, so there really should just be one endpoint.

It should be accept 1 to N messages.

API design?

Get /products/1/calculate/pricing/a.

for previous versions: /document-template/versions -> then have a list of previous document-templates versions on this page? But I dont think Nicks answer is good. You may implement the below design hints to achieve consistency: The forward-slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources.

Lets critical think it through, /v2/suppliers/id/{id} /v2/suppliers/code/{code}. You mentioned, that we should not use verbs and its better to use nouns to present a resource (since nouns have properties similarly to resources which have attributes), However in the controller type you are using verbs to refer to a resource, /checkout.

Next, URI does not limit the scope of what might be a resource; rather, the term resource is used in a general sense for whatever might be identified by a URI.

Fielding confirms this in his dissertation: At no time whatsoever do the server or client software need to know or understand the meaning of a URI they merely act as a conduit through which the creator of a resource (a human naming authority) can associate representations with the semantics identified by the URI. If its useful for grades to exist independent from students, you can make grades their own collection.

A controller resource models a procedural concept.

I don't like it that I create a new user via /groups endpoint.

A store is simply a collection of resources where we do not create any new resource in the system when we add something to the store; or we do not delete the resource from the system when we delete something from the store.

All resources have a set of methods that can be operated against them to work with the data being exposed by the API. Though, one suggestion is to have only one API "POST api/v1/tickets/messages". Would it be fair to say that resend, while not a direct CRUD type is actually a Transaction if we relate it to the Relational Database World?

A Uniform Resource Locator (URL) identifies the online location of a resource. To simplify the engine (and the lives of your API consumers), pick one to identify the target resource and use the query pattern for all others. tickets/messages collection in a collection, shouldnt be like this tickets/{id}/messages?action=sendmultiple sendsingle.

whose job is to dump the log into the system. e.g.

The URI would would be https://api.mycollegesite.com/courses/2019/fall, At the same time, you want to access the courses for which a particular student has registered for fall 2019. $_GET[song-management] = users; $_GET[{id}] = playlists; $_GET[page] = song-management; $_GET[find] = users; $_GET[select] = {id}; $_GET[show] = playlists; im a bit lost in how the APIs URI should behave and how in php would think.

You can use JSON object to send data to the API.

It is not also an optional thing in the sense that a certain set of objects are meant to hit one-tier vs the other.

A successful method used against your resource should return a 200-type response. How do I get the uri to retrieve a product with id 1 priced through pricing A?

2) Why somebody will filter a collection by device ids?

Coming back to our photosharing app, weve defined a /users and a /photos URL. Without understanding the whole use-case, it would not be correct to suggest appropriate naming.

I think it is fair for the store archetype to use singular nouns.

Hi, Great article, but I have a question.

Align your errors around the standard HTTP codes.

What is the best way to model the API to adhere to REST and URI guidelines? since you are filtering products it looks like a query parameter instead of a path parameter. e.g. If thats the case, only use of having customers/{Id}/ as prefix in URI would be while adding a new account. Visualize OpenAPI Specification definitions in an interactive UI.

As stated in the link, there are some considerations when doing this, like using only POST method, but is more clear this way when are you executing something or not. Focus on resource naming.

Nice catch on the two examples of controller resource.

(seriously wrong), What I mean is : http://api.example.com/device-management/managed-devices/ http://api.example.com/device-management/managed-devices/1 http://api.example.com/device-management/managed-devices/2 http://api.example.com/device-management/managed-devices/3. So isnt this wrong? For this requirement, do not create new APIs instead, enable sorting, filtering, and pagination capabilities in resource collection API and pass the input parameters as query parameters. Is there some propper way to do it?

Providing good feedback to developers on how well they are using your product goes a long way in improving adoption and retention.