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 1 year ago.
Improve this question
So my friend needed to develop new API for creating item, so he developed:
POST /new/item
POST /item/new
PUT /new/item
PUT /item/new
All of them call the same underlying function and accept same parameters.
I recommended that he uses only 1 instead of 4, but he says that there is no down side and he's giving the option for anyone who wants to integrate with this API to use whatever personal variation they like.
Question: Is it really that there is no down side by doing this in the long run?
There is no downside in regards to functionality, but an API with redundant endpoints will probably be
Harder to maintain. If a change to the endpoint is needed, it may have to be made four times depending on the setup
Confusing for users of the API. While I imagine it's the intention behind this setup to catch typos in URLs and still allow the API to work, documentation on the endpoints will be bloated and harder to read
Lacking consistent naming. Ideally, there is a logic behind how endpoints are named, allowing users to infer what an endpoint does by its name and verb (GET, POST etc). Having multiple naming schemes makes it harder to understand the naming.
There is no meaningful upside to making redundant endpoints, and I would recommended to use POST /item for creating a new item.
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 6 months ago.
Improve this question
I am new to REST API, and I am designing my own REST API for my web project.
Which of the followings is the better convention?
I want to access to the article that user ID 3 wrote.
/user/3/article
/article?user_id=3
Thanks.
Which of the followings is the better convention?
They are both fine.
/article?user_id=3 may prove more convenient if you are expecting to use HTML forms as a way of finding resources.
/user/3/article may prove more convenient if you expecting to use dot segments to describe other resource identifiers in the hierarchy.
What if I want to access to the fourth article that User ID3 wrote? /user/3/article/4 is appropriate? I think this hierarchy is unnecessarily deep.
Deep hierarchies are fine. Not using deep hierarchies are also fine.
In some designs, we'll use resource identifiers for items that are not part of the same hierarchy as the collection itself
context="/user/3/article" rel="item" href="/articles/4"
context="/user/3/article" rel="item" href="/articles/9"
context="/user/3/article" rel="item" href="/articles/16"
Think "web page with links"; if you can follow a link, you don't need a formula to compute the URI yourself.
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 2 years ago.
Improve this question
I have self-written API where urls are organized like:
GET /api/products
PUT /api/products/1
So there are controllers (ProductController.php, for example) and these controllers have four methods: get, post, put and delete.
Is this a right way to organize rest api?
If so, how to organize registration/authorization? Because both actions use POST method
Yes. I would recommend looking at how big companies are doing this kind of work. See how Github is structuring their API
Relies on what kind of authentication/authorization you want to use. Most companies choose Oauth with JWT, you could also use session-based authentication. For me, it's not clear what you exactly want to do. Maybe you can elaborate on that.
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 6 years ago.
Improve this question
I want to create multiple services, which support an SSO (Single Sign-On) service.
To simplify, a google like services. With a single account you can use all services (and you log in once).
I found many ideas, but I want to have some opinions on how to design these services, and which technologies are the most adequate:
many or one database ??
creating an auth api ??
sharing session ?
using nosql databse or not ?
duplicate user information foreach database ?
separate users tables on a single database ?
node js vs php !!
...
Update
I know this is opinion based (I ask for your opinions), I wish to have different proposition of design patterns.
It's purely theorique, so I can understand how it can be done.
This is totally opinion based, and will likely be closed. But...
Don't write your own auth service. There are many good packages out there, and very few people are really qualified to write authentication and authorization platforms. If you really don't want to use a pre-packaged solution, at least use one of them as a template.
Here is a good list of SSO solutions, pick one or two and give them a try. Many are free and open-source. I have had luck with OpenAM, but many others are also very good.
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've exposed a few methods and, while crystal clear on how they're supposed to be used, I'm sure that with time, the memory will fade and I'll be standing there like an idiot wonder why on Earth I haven't provided any help.
When we use WCF, there's the WSDL file. But I'm not aware of any corresponding functionality for WebAPI. Usually I add a Ping so that I can type in the URL window of my browser .../Service.svc/Ping, just to see that I a date back.
What would be an intuitive and (hopefully fairly) canonical approach? I'm thinking .../Help. Is there a better way?
Just pushing out help will only produce a huge string (XML or JSON formatted), which isn't very like-a-boss'y. Anonymous types can't be well handled without serialization. pushing out object typed entity breaks the connection.
I wish to have a built-in documentation on how to use the calls. The names themselves, of course, but also what values are treated (I had a case where the .../Donkey?scope={scope} pattern could be null or all and we though it was any, which took a while to figure out.)
You might checkout Swashbuckle which would allow you to generate Swagger documentation for your ASP.NET Web API controllers.
Anonymous types can't be well handled without serialization. pushing
out object typed entity breaks the connection
Are you really exposing anything like the above mentioned in your Web API contracts. I hope you don't.
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 looking for a nice way to generate documentation for a REST API. It doesn't need to actually connect with the code or anything, but it'd be awesome to be able to write the documentation as text files, point the tool at it, and generate some docs from it.
Anyone out there have any ideas? I know I'm being a bit vague, but, to be honest, I'm not quite sure what I'm looking for here--mainly an easy way to manage documentation.
According to Roy:
"A REST API should spend almost all of its descriptive
effort in defining the media type(s) used for representing
resources and driving application state, or in defining
extended relation names and/or hypertext-enabled mark-up
for existing standard media types."
Self-descriptiveness is one of the benefits of REST.
While not REST, I used Sphinx to document an XML-RPC API that consisted of an API reference and a tutorial. Sphinx adds some handy directives to ReStructuredText to get pretty much what you asked for: a collection of ReStructuredText formatted-text files that Sphinx turns into HTML and PDFs, complete with an index and table of contents. Sphinx is easy to use and well-documented; I don't think it would be an exaggeration to say you could get started with it in about ten minutes.
Some RESTful systems are actually able to write their own API. Have a look at RESTx, which does just that: You write your components and then create new web services by sending parameters for those components to the server (either as JSON or via a web form). You then get a URI back for those parameters. Accessing it calls the component with the parameters and you retrieve the results.
At any rate, the components as well as the created RESTful web services get an automatically generated documentation, which is browseable and can be retrieved either in HTML or JSON format.