What is the best design for a RESTful URI with a few required parameters?

Question

I am looking to find out if more experienced web service veterans can comment on the best way to develop a RESTful URI where I need the required parameters. For example, I would like to create a URI that requests data:

example.com/request/distribution 

However, from my understanding that the approach is that more data should be returned at higher levels, while more detailed data will be returned when applying more specific URI keywords, but in my case I need at least 3 values ​​for this , These 3 values ​​are date value, account value, and distribution code eigenvalues. For example:

 example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C 

Is this a "RESTful" URL or is there a better approach that makes sense? Any input is welcome.

By the way, Python is the language of choice. Thanks!

Answer 1

URIs by definition cannot be “unRESTful” because the URI specification was oriented towards the REST architectural style. As you use a URI, you can break the REST style:

• Client-server restrictions should not be followed; for example, using WebSockets to implement a push server.
• There is no restriction on "resource identification"; for example, by using a portion of the URI to specify control data or resource metadata, rather than stick to the identification of the resource or by identifying the resource using some mechanism other than the URI (for example, session state or other out-of-band mechanisms).
• It does not follow the limitations of “manipulating resources through representations”; for example, using the request part for a URI to pass state.
• There is no restriction on “self-describing messages”; for example, using an HTTP GET to change state or pass JSON with the content type "text / html".
• The limitations of "hypermedia as the engine of application state" should not be followed; for example, do not provide user agent hyperlinks, but instead assume that they will build them using out-of-band knowledge.
• The "tiered system" limitation does not follow, requiring the client to know the details of how the server works (especially requiring the client to provide them in the request).

None of the above is a bad choice. They may be the best choice for your system, as they contribute to specific architectural properties (such as efficiency or security). They simply are not part of the REST style.

The fact that your resource has been identified by several required segments is an integral part of URI design. As Anton points out, the choice between example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C and, say, example.com/accounts/123/distributions/20030102/1A;1B;1C is purely one of data design, not a problem for the URI itself. There is nothing wrong with, for example, responding to a PUT, POST, or DELETE request for the first. A client who could not follow the link to one will be considered broken. A system that expected any of them to be provided to the client by some means other than a hypermedia response would be considered "unRESTful".

Answer 2

It is better to create a RESTful API first in terms of resources rather than a URI. This has more to do with your data design than, say, your choice of language.

For example, you have a Distribution resource. You want to present it in your web interface, so it must have a corresponding unique resource identifier (URI). It should be simple, readable and unlikely to change. This would be a worthy example:

 http://example.com/api/distribution/<some_unique_id> 

Think twice before investing more things and hierarchies in your URIs .

You do not want to change your URIs as your data model or authentication scheme is evolving. Changing the uncool URI is a pain for you and the developers who use your API. Thus, if you need to authenticate with the backend, you should probably use GET parameters or HTTP headers (for example, the AWS S3 API allows both ).

Enabling too many GET parameters (e.g. http://example.com/api/distribution/?id=<some_unique_id> ) may sound like a bad idea, but IMO doesn't really matter [0] - while you keep your documentation The API is accessible and relevant.

[0] Update: for the read-only API, at least. For the CRUD API, as @daniel noted, this is more convenient when you have endpoints, as in the first example above. Thus, you can make good use of HTTP methods by including GET, PUT, DELETE for individual resources in /api/distribution/<id> and POST for /api/distribution to create new distributions.

While researching the answer, I found a nice presentation about the RESTful API: Designing HTTP Interfaces and RESTful Web Services .

Answer 3

The RESTful method should represent the data as a resource, not the parameters for the request:

 example.com/distribution/123/20030102/1A;1B;1C 

Answer 4

When you think about RESTful, most of the time you should also think about CRUD.

 example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C 

Great for a GET request to show something (R in CRUD).

But what URLs are you considering for CUD-Parts?