RESTApi EndPoint GET Multiple Resources

Question

The operation bellow retrieve of all books only the ones that are into the request. It is clearly a GET operation.

From your perspective what is better ( pro/cons ) of doing those two bellow:

Note:

GET - api/library/2/books/

Retrieves all the books from the Library 2.

Using GET:

GET - api/library/2/books/3/5/10/33/...../pages

Using POST:

POST - api/library/2/books/pages

Body:

{
    "books_id": [
        2,
        30,
        40,
        20,
        30
    ]
}

I’m in a real doubt here between using POST or GET methods to implement that. Books Ids on URL will get really messy if there was like 100-200 books to retrieve. I want some enlightenment here.

I'm using PHP to handle the Rest Application and all those methods above are valid.

score 5 · Accepted Answer · edited Oct 07 '21 at 08:14

This operation matches the standard semantics of the GET method, and therefore the expectations of various software. For example:

many HTTP clients know that they can automatically retry GET requests in case of errors
it’s easier to cache responses to GET

If your book IDs are independent from library IDs, then it may be better to drop the reference to the library, and do just

GET /api/books/3,5,10,33/pages

Books Ids on URL will get really messy if there was like 100-200 books to retrieve

If every book ID is 6 digits long, this adds up to just 700-1400 bytes. This is well within the range supported by any good HTTP client. To really push the practical limits on URL length, you would need many more books — but do you really need (or want) to support retrieval of so many pages at once?

(Alternatively, though, your book IDs might be much longer — perhaps UUIDs.)

If you do run into limits on URL length, it’s OK to use POST to a dedicated “endpoint”:

POST /api/books/bulk-pages

{"books_id": [3, 5, 10, 33]}

POST is defined in RFC 7231 § 4.3.3 as a sort of “catch-all” method:

process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others):

o Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;

As a curiosity, there has been a recent attempt to standardize a SEARCH method that would allow request payloads like POST, but also be safe and idempotent like GET. Unfortunately, that effort has stalled, so you probably shouldn’t try to use SEARCH now.

Technically, the protocol allows you to send a payload even with a GET request, but as RFC 7231 § 4.3.1 notes, this is unusual and may cause trouble:

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

You answer was very good and it was the closest I wanted. I can't drop the Library Reference because of the possibility of having books with same Id's. Whats the semantic difference between using commas or slash ? In your example you separate the books ids using commas, what would be the impact of using slashes ? — Igor Morse, Aug 05 '17 at 23:28
@IgorMorse In a URL path, slashes separate levels of hierarchy (like folders in a file system). This affects URL joining and normalization. Commas don’t have special meaning in a path, so you can use them as you want. — Vasiliy Faronov, Aug 05 '17 at 23:32
Thanks for your response! Your answer was the one that I was wishing for, thanks for the effort. — Igor Morse, Aug 06 '17 at 04:48

score 2 · Answer 2 · edited Oct 07 '21 at 11:04

2

Query parameters

For retrieving multiple books, consider query parameters (using ?):

GET /api/library/2/books?id=3,5,10,33

Matrix parameters

For retrieving pages of multiple books, you could consider matrix parameters (using ;):

GET /api/library/2/books;id=3,5,10,33/pages

Then you also can use query parameters to filter the pages.

^{• For more details about matrix and query parameters, refer to this question.}

^{• Also refer to the following sections of the RFC 3986 for more details: §3.3 Path and §3.4 Query}

edited Oct 07 '21 at 11:04

Community

1
1

answered Aug 05 '17 at 10:10

cassiomolin

124,154
35
280
359

This is the first time I'm seeing Matrix parameters. This could add some complexity to my EndPoint as I use Regular Expression to map the routes. `GET - api/library/2/books/3/5/10/33/...../pages` Using this as a variation would be considered wrong ? – Igor Morse Aug 05 '17 at 23:19
1

@IgorMorse Once slashes represent hierarchy, it doesn't make any sense. – cassiomolin Aug 06 '17 at 00:27

score 0 · Answer 3 · answered Aug 05 '17 at 07:23

0

POST in your case does not look semantically correct. Maybe you can try query params like

GET - api/library/2/books/pages?ids=[1,2,3,4,5]

answered Aug 05 '17 at 07:23

Onur Okyay

190
1
10

RESTApi EndPoint GET Multiple Resources

3 Answers3

Query parameters

Matrix parameters