Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm designing a REST API and trying to decide which is the more correct way of returning a single resource:
/resource/{id}
or
/resource/{name}
The ID would be immutable, so I'm thinking that it would be better to select by it, but name would be more friendly looking. What is the best practice? I've seen both used before "in the wild".
Basically REST is built on top of unique IDs, thus:
GET /resources/{id}/
should be used. However, there's nothing that prevents you from making name field unique (now it behaves as plain old ID) and build REST on top of this unique ID.
If this is not what you need and name cannot be made unique, then another option is to implement filtering via name:
GET /resources?name=<SOME_NAME>
It also should be resources (plural) since it indicates that there's a collection under the hood.
Whether using name instead is practical comes down to your business case.
Will 'name' always be unique? Or will the application deal with there being more than one occurrence?
Are 'pretty' URLs important? In most applications I've worked on, querying uses unique IDs which are never exposed to the end-user, as they have no business meaning whatsoever. They are in effect surrogate primary keys.
/resource/{id} is more technically correct, but if it were me, I'd allow both. Assuming names can't contain ONLY numbers, and ids can ONLY be numbers, you could easily detect which was supplied and allow for either to be used. ;)
This is good question .. it depends on business case example if api is used through cli like docker then you might want to use user friendly ids like name
But as soon as it become part of URL it has limitations like ASCII (to avoid url encoding or loss of readability ) char only and some defined length like 128 chars etc.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I am wondering what is the recommended type for PK in sql server? I remember reading a long time ago this article but now I am wondering if it is still a wise decision to use GUID still.
One reason that got me thinking about it is, these days many sites use the id in the url for instance Course/1 would get the information about that record.
You can't really do that with a guid, which would mean you would need some new column that would be unique and use that, what is more work as you got to make sure each record has a unique number.
There is never a "one solution fits all". You have to carefully design your architecture and select the best options for your scenario. Both INT and GUID types are valid options like they've always been.
You can absolutely use GUID in a URL. In fact, in most scenarios, it is better to use a GUID (or another random ID) in the URL than a sequential numeric ID for security reason. If you use sequential ID, your site visitors will be able to easily guess other users' IDs and potentially access their contents. For example, if my profile URL is /Profiles/111, I can try Profile/112 and see if I can access it. If my reservation URL is Reservation/444, I can try Reservation/441 and see what happens. I can easily guess other IDs in the system. Of course, you must have strong permissions, so I should not be able to see those other pages that don't belong to my account, but if there is any issues or holes in your permissions and security, a breach can happen. While with GUID and other random IDs, there is no way to guess other IDs in the system, so such a breach is much more difficult.
Another issue with sequential IDs is that your users can guess how many accounts or records you have and their order in your database. If my ID is 50269, I know that you must have almost this number of records. If my Id is 4, then I know that you had a very few accounts when I registered. For that reason, many developers start the first ID at some random high number like 1529 instead of 1. It doesn't solve the issue entirely, but it avoid the issues with small IDs. How important all that guessing is depends on the system, so you have to evaluate your scenario carefully.
That's on the top of the benefits mentioned in the article that you mentioned in your question. But still, an integer is better in some areas, so choose the best option for your scenario.
EDIT To answer the point that you raised in your comment about user-friendly URLs. In those scenarios, sequential numbers is the wrong answer. A better solution is a unique string in the URL which is linked to your numeric ID. For example, the Cars movie has this URL on IMDB:
https://www.imdb.com/title/tt0317219/
Now, compare that to the URL of the same movie on Wikipedia, Rotten Tomatoes, Plugged In, or Facebook:
https://en.wikipedia.org/wiki/Cars_(film)
https://www.rottentomatoes.com/m/cars/
https://www.pluggedin.ca/movie-reviews/cars/
https://www.facebook.com/PixarCars
We must agree that those URLs are much friendlier than the one from IMDB.
I've worked on small, medium, and large scale implementations(100k+ users) with SQL and Oracle. The major of the time PK type of INT is used when needed. The GUID was more popular 10-15 years ago, but even at its height was not as populate as the INT. Unless you see a need for it I would recommend INT.
My experience has been that the only time a GUID is needed is if your data is on the move or merged with other databases. For example, say you have three sites running the same application and you merge those three systems for reporting purposes.
If your data is stationary or running a single instance, int should be sufficient.
According to the article you mention:
GUIDs are unique across every table, every database, every server
Well... this is a great promise, but fails to deliver. GUID are supposed to be unique snowflakes. However, reality is much more complicated than that, and there are numerous reasons why they end up not being unique.
One of the main reasons is not related to the UUID/GUID specification, but by poor implementations of it. For example some Javascript implementations rank as the worst ones, using pseudo random numbers that are quite predictable. Other implementations are much more decent.
So, bottom line, study the specific implementation of UUID/GUID you are and will be using. Don't just read and trust the specification. Otherwise you may be up for a surprise, when you get called at 3 am on a Saturday night by angry customers.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I am currently working for a company writing use cases. They have a template which mixes them with data dictionaries. I've never seen this kind of template. I searched the web looking for answers. I am wondering if this is a correct practice/method. If it is, does this template have an specific name? They are calling it use case template, I do think is wrong to call it that way.
This is an example:
Note: This template has a valid use case written above of it (not shown in here).
Step: 1
Actor: Application
Action:
Display login page
Login page section has the following fields:
- Username
- Password
- Submit button
Here's the description of the fields for this section:
- Username - textbox field, required, no default value, allow 10 character maximum
- Password - textbox field, required, no default value, allow alphanumeric characters, allow a maximum of 30 characters
Step: 2
Actor: User
Action:
User enters username & password
User hits submit button
Step: 3
Actor: Application
Action:
The app allows access to the page.
This is common practice. I don't know if he's the inventor, but Alistair Cockburn provides such templates along with rules how to fill them in.
However, for the methodological approach and much of the background info needed in use case synthesis I always recommend Bittner/Spence. (Note: there is a Word-version of this book when you google for it. I have not idea now this infringes copyrights, but the money for the book is worth it.)
Yes, I've seen this before, but it is not common practice to specify the data requirements in such detail in the use case scenario. In fact, in your example, they are even trying to describe the user interface details in words.
I would recommend, like you expect, to have a separate data model (which is a bit more than just a data dictionary) and specify the data requirements over there. For the user interface, it would be better to create a prototype or wireframe. Too often, IT departments tend to create their own methodologies instead of buying a good book.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I'm developing a restful API using NodeJS. To give you a little more insight in my application:
My application has surveys. A survey contains questions which in their turn has choices.
To add a question, you need to provide the id of the survey in the body of the post. To add an option, you need to provide the id of the question.
Now for the API routes. What would be better:
Option 1
/api/departments
/api/surveys
/api/questions
/api/choices
Option 2
/api/departments
/api/departments/department_id/surveys
/api/departments/department_id/surveys/survey_id/questions
/api/departments/department_id/surveys/survey_id/questions/question_id/options
The last one seems more logical because I don't need to provide the id of the parent in the body of the post.
What is best practice to use as endpoints?
I don't think there's a "best practice" between the two; rather, it's about having the interface that makes the most sense for your application. #2 makes the most sense if you're typically going to access the surveys on a per-department basis, and also makes sense in terms of accessing questions on a per-survey basis. If you wanted to eliminate the per-department part, you'd do something that's kind of a mix of the above:
/api/departments
/api/surveys
/api/surveys/survey_id/questions
/api/surveys/survey_id/questions/question_id/options
If you DO want to go by per-department, I'd change #2 so that instead of /api/departments/surveys one would access /api/departments/department_id/surveys ...
But without knowing more about the application, it's difficult to know what the best answer is.
Do surveys contain anything besides questions? do questions contain anything besides choices? The reason I ask is that if the answer to both is no then I'd actually prefer something like this:
/api/departments/ # returns a list of departments
/api/departments/<survey-id>/ # returns a list of questions
/api/departments/<survey-id>/<question-id>/ # returns a list of choices
/api/departments/<survey-id>/<question-id>/<choice-id> # returns a list of options
or something to that effect. Basically, I like to keep the concept of "containers" and "data" rigid. I like to think of it like a file system.
So if the concept ends in an "s", it's a container (and I'd like the route to end with a "/" to indicate that it acts like a folder, but that's a nit).
Any access to "/" results in the element at that index, which of course can be another container. Similar to directory structure in a file system. For example, if I were to lay these out in a file system, I might come up with something like this:
+ /api/departments/
|-----------------/human-resources/
|---------------/survery-10/
|----------/choice-10
The choice depends on whether resources are owned or shared by higher-level resources; whether you want cascading delete or not. If owned (with cascading delete), choose option 2 and if shared, choose option 1.
If a survey is deleted, I guess you want to delete all questions and options with it (cascading delete). This matches well with option 2, because if you delete resource /api/departments/departmentid/surveys/surveyid, you naturally also delete all subresources /api/departments/departmentid/surveys/surveyid/questions/....
On the other hand, if you want the option to share questions among multiple surveys and share surveys among multiple departments, then option 1 is better.
Of course, you can also have a mix of option 1 and option 2, if some resource types are owned and others are shared.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I have some trouble modeling the resources in a domain to fit with a REST API. The example is obviously contrived and simplified, but it illustrates 2 points where I'm stuck.
I know that:
a user has pets
a pet has multiple names - one by each member of the family
a pet has: a date of birth, a date of death and a type (dog,cat...)
I need to be able to query based on dates (actually the date, or range of dates is mandatory when asking about pets). E.g.: tell me what pets I have now; tell me what pets grandma says we had 5 years ago until 3 years ago.
How should I handle dates?
a. in the query string: /pets/dogs/d123?from=10102010&to=10102015 (but as I understand, query string is mostly for optional parameters; and date/range of dates is needed. I was thinking of having the current date as default, if there's nothing in the query string. Any thoughts on this?)
b. somewhere in the path. Before /pets? This seems a bit weird when I change between a date and a range of dates. And my real path is already kind of long
How should I handle multiple names?
The way I see it, I must specify who uses the name I'm searching for.
/pets/dogs/rex -> I want to know about the dog called rex (by whom, me or grandma?). But where to put grandma?
I've seen some people say not to worry about the url, and use hypermedia But the way I understood that(and it's possible I just got it wrong) is that you have to always start from the root (here /pets )and follow the links provided in the response. And then I'm even more stuck(since the date makes for a really really long list of possibilities).
Any help is appreciated. Thanks
What might be useful in such scenarios is a kind of resource query language. It don't know the technology stack that you use, but a JavaScript example can be found here.
Absolutely do not put any dates in the path. This is considered as a bad style and users may be confused since, they most of them may be not used to such strange design and simply will not know how to use the API. Passing dates via query string is perfectly fine. You can introduce a default state - which is not a bad idea - but you need to describe the state (e.g. include dates) in the response. You can also return 400 Bad Request status code when dates range is missing in request. Personally, I'd go for default state and dates via query string.
In a such situation the only thing that comes to my mind is to reverse the relation, so it would be:
/users/grandma/dogs/rex
or:
/dogs/rex/owners/grandma
What can be done also is to abandon REST rules and introduce new endpoint /dogs/filter which will accept POST request with filter in the body. This way it will be much easier to describe the whole query as well to send it. As I mentioned this is not RESTful approach, however it seems reasonable in this situation. Such filtering can be also modeled with pure REST design - filter will become a resource as well.
Hypermedia seems not the way to go in this particular scenario - and to be honest I don't like hypermedia design very much.
You can use the query string if you want, there is no restriction about that. The path contains the hierarchical, while the query contains the non-hierarchical part, but that is not mandatory either.
By the queries I suggest you to think about the parameters and about what will be in the response. For example:
I want to know about the dog called rex (by whom, me or grandma?)
The params are: rex and grandma and you need dogs in the response.
So the hyperlink will be something like GET /pets/dogs/?owner=grandma&name=rex or GET /pets/dogs/owner:grandma/name:rex/, etc... The URI structure does not really matter if you attach some RDF metadata to the hyperlink and the params e.g. you can use the https://schema.org/AnimalShelter vocab. Ofc. this is not the best fit, because it does not concern about multiple names given by multiple persons, but it is a good start to create your own vocab if you decide to use RDF.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
PostgreSQL provides the ability to magically generate constraint names in statements like CREATE TABLE, ALTER TABLE if none are provided explicitly. The naming convention is well known and I personally like it very much. But how stable and official is it? Is it something which one can rely on for different major releases or even the next 50 years?
I always had the impression that this is an implementation detail and while a lot of people rely on it, one shouldn't and always use explicit names to properly document things instead. I think I've read something like that in the official documentation in the past, but couldn't find it anymore...
So is there a definitive, official statement how reliable this naming scheme is or if users should always try to provide explicit names?
Strictly, if it's not in the documentation, you should not rely on it.
The docs only say:
If you don't specify a constraint name in this way, the system chooses a name for you.
so strictly I should recommend not baking the constraint names into the application unless you specify them explicitly in the SQL. This will also make the connection more apparent when reading the SQL - you bothered to specify constraint names for a reason.
That said, constraint name generation has not AFAIK changed, at least since I started using Pg around 7.4. So while it's not part of the official documented API, it's probably also not especially bad to rely on it. Also, constraint names are always going to be preserved by pg_dump and pg_upgrade, so it likely doesn't matter much unless you are doing a clean reload into a new version that has changed default constraint name generation.
TL;DR: It doesn't look like they're officially defined and documented, but they're unlikely to change, and if they do the impact is minimal. So relying on them is probably OK. Just document that in the app.