Say, for example, I had a REST api url design with "Customer" as a resource.
Now, I want to be able to list all customers, find a specific customer by ID or Email address
Also, I want to be able to add a new customer...
Are these example URIs right?
Or should I be doing it another way..?
/customer/1234
get customer with id 1234
/customer/email/john#smith.com
get customer with email address
[POST]
/customer/
creates a new customer
/customers/
list all customers (notice pluralization)
In my experience RESTful APIs use a single resource path that is plural. The idea is that you have customers and when you want to interact with a customer you are interacting with the customers resource in general.
GET /customers to get a list of customers.
POST /customers to create a new customer.
GET /customers/:id to get a specific customer with a unique id. (Generally not an attribute of a customer like email)
GET /customers?email=bob#example.com to get customers with a specific attribute value.
Apigee has a blog post that covers pluralization that you might want to read.
If I was designing this API I would start with a generic hypermedia type like HAL and design a root representation that provides me access to the various scenarios you describe using links and uri templates.
e.g
GET /api
=>
<resource>
<link rel="urn:mycompany:customer" href=".../{id}"/>
<link rel="urn:mycompany:customers" href="..."/>
<link rel="urn:mycompany:customersearch" href="...{?email}"/>
</resource>
I have not filled in the actual URLs because from the perspective of the consumer of the API it really does not matter how those URLs are structured. Do whatever is easiest in you server framework. Don't worry if you get it wrong, you can change it later and your clients won't break because they should discover the URL from the root representation.
It is fairly common to assume that POSTing a customer to a collection of customers will create a new Customer, so you could just require your consumers to use that link. Or if you wish to be more explicit you could define a new link relation that provides a URL for creating Customers.
This is how I would do it:
/customer/1234
customer/john#smith.com
or (if email not guaranteed to be unique)
customers/search?email=john#smith.com
[POST]
/customers/ (notice the plural, same as below)
[GET]
/customers/
Cheers,
Ferenc
Why not be robust and enable both /customer and /customers?
GET /customer/1234 or /customers/1234 retrieves the same resource.
GET on /customer or /customers gives a list of all customers.
POST to /customer or /customers creates a new customer.
Related
A person can have many reviews. My endpoint to CREATE a new review is:
post /person/{id}/reviews
How about the endpoint to UPDATE a review? I see two options:
Stick to the parent resource: patch /person/{person_id}/reviews/{id}
Only have reviews in the URI: patch /reviews/{id}
I could be sold on using either of them:
It's consistent with the previously defined endpoint, but {person_id} is not needed.
It's 'efficient' as we're not specifying a parameter ({person_id}) that is not really needed. However, it breaks the API convention.
Which one is preferable and why?
The client shouldn't have to know about ids at all. After a client creates the review, the response should include the URI to the new review like this:
HTTP/1.1 201 Created
Location: /person/4/reviews/5
The client now has the full URL to the review, making it completely irrelevant how it looks like and what information is here.
Don't forget that the URL itself is a system to create globally unique IDs, that embed not just it's own unique identity but also information on how to access the data. If you introduce a separate 'id' and 'person_id' field you are not taking advantage of how the web is supposed to work.
In terms of API design, without knowing too much detail about OP's situation I'd walk along these guideposts:
Only have reviews in the URI: patch /reviews/{id}
It's 'efficient' as we're not specifying a parameter ({person_id})
that is not really needed. However, it breaks the API convention
The "efficiency" allows for a more flexible design. There's no existing API convention broken at this point. Moreover, this approach gives you the flexibility to avoid the need of always needing the parent resource ID whenever you display your items.
Stick to the parent resource: patch /person/{person_id}/reviews/{id}
It's consistent with the previously defined endpoint, but {person_id}
is not needed.
The consistency aspect here can be neglected. It's not beneficial to design endpoints similarly to other endpoints just because the previous ones were designed in a certain way.
The key when deciding one way or the other is the intent you communicate and the following restrictions that are put on the endpoint.
The crucial question here is:
Can the reviews ever exist on their own or will they always have a parent person?
If you don't know for sure, go for the more flexible design: PATCH /reviews/{id}
If you do know for sure that it always will be bound to a particular person and never can have a null value for person_id in the database, then you could embed it right into your endpoint design with: PATCH /person/{person_id}/reviews/{id}
By the way, the same is true for other endpoints, like the creation endpoint POST /person/{person_id}/reviews/{id}. Having an endpoint like this removes the flexibility of creating reviews without a person, which may be desirable or not.
I wanted to get opinion on resource granularity. Say, I have a an domain entity called "magazines". But there are different types of magazines, including Sports, Nature, Automobiles, Computers and Aeroplanes, etc.
When I want to create a new "sports" magazine, should I be using construct such as:
PUT /magazines
PUT /sports-magazines
PUT /magazines/sports
When I want to get a specific sports magazine, should I be saying:
GET /magazines/{id}
GET /sports-magazines/{id}
GET /magazines/sports/{id}
If I want to get sports magazines for the year 2001, should I be using:
GET /magazines?type=sports&year=2001
GET /sports-magazines?year=2001
GET /magazines/sports?year=2001
And finally, if I want to return how many pages each type of magazine has for January 2001 publication, how would I do that? Do I need to create a new pages resource for that? Or make two independent requests or something else? First of these is listed below:
GET /magazines/pages?type1=sports&type2=nature&year=2001&month=01
GET /sports-magazines/pages?type=nature&year=2001&month=01
Given these scenarios how would you model your resources?
I have a an domain entity called "magazines". But there are different types of magazines, including Sports, Nature, Automobiles, Computers and Aeroplanes, etc.
Important thing to understand: resources aren't domain entities. Your resource model is a facade that sits in front of your domain model.
Notice, for example, that this resource (REST API Resource Granularity) describes not only your question, but also my answer.
PUT probably is NOT what you want for "create a new resource" unless the client is already in position to know what URI should be used for the new resource. The target URI of a PUT request is the same URI that we expect to use later to GET the data
PUT /magazines/{id}
GET /magazines/{id}
In the case where we don't expect the client to know what the URI is going to be... well, we don't have an HTTP method that means precisely that, so we fall back to using POST (see Fielding, 2009).
POST /magazines
201 Created
Location: /magazines/12345
Note that the machines don't care if the URI of the created resource(s) match the target URI of the POST request.
REST really doesn't care what spelling conventions you use for your resource identifiers (in much the same way that the machines don't care what spelling conventions you use for variable names).
GET /magazines?type=sports&year=2001
GET /sports-magazines?year=2001
GET /magazines/sports?year=2001
GET /magazines/sports/year=2001
GET /magazines/sports/2001
Those are all fine; there are trade-offs. Key value pairs encoded into a query string make creating URI with HTML forms easier, using path segments makes relative resolution easier.
I want to return how many pages each type of magazine has for January 2001 publication
Creating a new URI with that information is fine. Extending the schema of your existing resources to include that information is also fine.
When designing a restful API, resource ownership is a consideration when designing the URIs. In my case, I'm working on an API where two of my entities will be people and addresses. Each person can have more than one address, so in the database they'll be in separate tables.
Normally I just use auto incrementing keys, so each new record adding increases the ID number.
A thought I had was that if I uses this approach, it would effectively produce a URI like this:
/people/11/addresses/52
In that case, person 11 doesn't have 52 addresses. It's just person 11, who has an address with an ID of 52.
The other side of it is whether I would even be using a URI like that. Addresses generally won't be retrieved on their own by the client, but as part of a person object retrieved by a single API call (/people/11 would retrieve all addresses associated with that person).
Anyway, I guess the question here is about best practices. Is it common to see an entity owned by another with ID values like that? What are the general practices with this?
Your method is correct.
Also These are general rules (reference):
- An API is a user interface for a developer - so put some effort into making it pleasant
- Use RESTful URLs and actions
- Use SSL everywhere, no exceptions
- An API is only as good as its documentation - so have great documentation
- Version via the URL, not via headers
- Use query parameters for advanced filtering, sorting & searching
- Provide a way to limit which fields are returned from the API
- Return something useful from POST, PATCH & PUT requests
- HATEOAS isn't practical just yet
- Use JSON where possible, XML only if you have to
- You should use camelCase with JSON, but snake_case is 20% easier to read
- Pretty print by default & ensure gzip is supported
- Don't use response envelopes by default
- Consider using JSON for POST, PUT and PATCH request bodies
- Paginate using Link headers
- Provide a way to autoload related resource representations
- Provide a way to override the HTTP method
- Provide useful response headers for rate limiting
- Use token based authentication, transported over OAuth2 where delegation is needed
- Include response headers that facilitate caching
- Define a consumable error payload
- Effectively use HTTP Status codes
Also there are lots of references on web. This page is a good start.
and these are also useful: slide1, devzone tutorial
You would normally use a resource like: /people/11/addresses/52 when you return the details of an address in a personalised manner for the people entity.
If for example, you have entities: people and office which can have addresses, and for people you want to display only the country and for offices you want to display all the details of addresses.
On the other hand, if you don't need customization you can also use an url like: /address/12 , since it will be easier to cache a response like that.
Addresses generally won't be retrieved on their own by the client,
but as part of a person object retrieved by a single API call
(/people/11 would retrieve all addresses associated with that person).
If this is the case you can leave out the detailed addresses url.
Yes, That's correct way to apply many to many relation in APIs. Just remember to check id2 belongs to id1 when returning the value.
For retrieving all the addresses the correct call is /people/11/addresses. Then you know you have to call a join query.
I'm working on REST Api suing Python Flask, as I have more and more routes, its hard to manage all the resource urls.
Right now, I'm confused which one is better practices of URL parameters. Examples below:
Get a list of courses with limits:
/courses/<int:lim> OR /courses/list?lim=10
Get a specific course:
/courses/<code>/<section> OR /courses/show?code=cs100§ion=1
Get a list of students in specific course:
/courses/<code>/<section>/students OR /students/show?code=cs100§ion=1
Should I pass query parameters using / or by doing ?
The only reason I'm using / is that there's no conflict in query.
If I have these two URL for two different queries, how can I fix it so I can query base on the parameters:
/students/show?code=cs100§ion=1 (Get all students in that course)
/students/show?id=123456789 (Get the specific student)
The URL should identify a resource or collection of resources. Any options you want to give the client, such as pagination, limits, filtering, sorting, etc. I think is best to include in the query string or in HTTP headers.
So regarding your specific questions:
Get a list of courses with limits: /courses/<int:lim> OR /courses/list?lim=10
Neither one. Use /courses?lim=10. No need to have a /list component, that is an action, not a resource.
Get a specific course: /courses/<code>/<section> OR /courses/show?code=cs100§ion=1
The first. Once again, /courses/show indicates an action, you want URLs to be links to resources, in this case your course.
Get a list of students in specific course: /courses/<code>/<section>/students OR /students/show?code=cs100§ion=1
The first, same reason as the previous one.
I have given REST API talks at the last two PyCon conferences, feel free to check them out if you want to learn more API design best practices:
PyCon 2014: Writing RESTful Web Services with Flask
PyCon 2015: Is Your REST API RESTful?
EDIT: I've solved my issues (for now at least).
I've recently been working with the Zendesk REST Api and their use of the custom "X-On-Behalf-Of" header for looking up tickets opened by a particular user got me thinking about Restful Api design choices (in no specific language, more of a how to name URIs question). I've also read this related question on Custom HTTP headers, but it left me with more questions than answers.
Say I have an example restful web service dealing with rental apartment applications where clients use Basic Auth (keep it simple) to authenticate. Define the basic data as such:
Users (can be of type landlord or renter)
Forms (which consist of one or more Document resources and some form meta data like form name and version info)
And then some type of resource corresponding to Rental Applications, which ties together Forms, Applicants (one or more renters), Landlord, and some metadata like status and dates.
I'm struggling to properly model the URIs for the Applications resource in general, and more specifically with respect to a clients role. (assume api root is https://api.example.com/)
How do I allow a Landlord to fetch a list of applications sent to them? My intuition says make a request to "GET /applications" and Basic Auth lets the server know which user to build the list for; likewise "GET /applications" requested by a Renter would return a list of applications they've sent...but I'm not confident this is a solid design in general to mix and match sender vs. recipient lists at the same URI. Should I be thinking about the "/applications" resource differently, and perhaps allowing a hierarchy like "/applications/[USER_IDENTIFIER]" for each user instead?
Also, regardless of my applications URI design, assume a Landlord is able to create an application on behalf of a renter. Is this better accomplished by sending a custom header like "X-Create-On-Behalf-Of: somerenter#example.com" with the PUT/POST creation request? Or should my schema define a field which allows for this alternative scenario.
I'm very much an amateur at this, so I'm open to any criticism of my assumptions/design, as well as any pointers for learning more about designing RESTful api's. Thanks for reading.
I think I've found a solution.
Landlords and Renters are really just subclasses of the same object, which I'll call Party (as in party to a transaction, not birthday party). So then each one has their own resource, named like /party/PARTY_ID.
It's easy to extend this to see that /party/SOME_LANDLORD/applications and /party/SOME_RENTER/applications solve my issues. It also removes my need to consider custom headers.