Best practise for trailing slashes on endpoints

[SamEdwardes]

I have noticed that sometimes trailing slashes are used, and sometimes they are not used for API endpoints.

Is it best practice to define the endpoint with a trailing slash or without a trailing slash? What do you need to consider when designing?

Example

For example, take this app:

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]


@app.get("/items2")
async def read_item2(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

Using a trailing slash /items/

The /items/ endpoint has a trailing slash.

This will work:

$ curl -X 'GET' -H 'accept: application/json' 'http://127.0.0.1:8000/items/'
[{"item_name":"Foo"},{"item_name":"Bar"},{"item_name":"Baz"}]

This will not work (no data/error/warning) is returned:

$ curl -X 'GET' -H 'accept: application/json' 'http://127.0.0.1:8000/items'

Sidenote - if I paste http://127.0.0.1:8000/items into my browser, it will work. The browser automatically adds the trailing slash.

Not using a trailing slash /items2

I created an endpoint that does the same thing but has no trailing slash this time.

This works:

$ curl -X 'GET' -H 'accept: application/json' 'http://127.0.0.1:8000/items2'
[{"item_name":"Foo"},{"item_name":"Bar"},{"item_name":"Baz"}]

This will not work (no data/error/warning) is returned:

$ curl -X 'GET' -H 'accept: application/json' 'http://127.0.0.1:8000/items2/'

Sidenote - if I paste http://127.0.0.1:8000/items2/ into my browser, it will work. The browser automatically removes the trailing slash.

[zoliknemet]

I personally do not like trailing slashes because you are accessing RESOURCE. You can also look at this like you are accessing file: /folder/subfolder/file - there is no slash at the end...

Try to answer this: How will you put query parameters when you have slash at the end?

[SamEdwardes]

I do not think there is any issue technically adding query parameters when there is a slash at the end. For example, check out this page of the FastAPI docs https://fastapi.tiangolo.com/tutorial/query-params/:

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

In the docs, the following example URL is given:

http://127.0.0.1:8000/items/?skip=0&limit=10

I agree with you that it makes more sense not to use a trailing slash. But it looks like both options work?

[GonnaFlyMethod]

Personally, I prefer not to add trailing slashes at the end of paths.
I believe that API should be predictable and it should follow some basic rules in its design.
zoliknemet has mentioned the query parameters after the trailing slashes. For me it's way more predictable and convenient to limit number of users like that: /users?limit=20 than /users/?limit=20

[Danstiv]

The browser automatically adds the trailing slash.

automatically removes the trailing slash.

There is no magic, Fastapi returns 307 redirects, you can add the -v flag to curl to see them.

[YuriiMotov]

There is no strict rule, but seems that most people prefer not to add trailing slashes.

Spectral (popular linting tool for openapi) by default has path-keys-no-trailing-slash rule enabled (ensures there is no trailing slashes).

[raceychan]

If you follow RESTFUL api design, you would avoid using trailing slash in most cases.

The general rule is that, you use static path for a collection of resources, such as /users, use /users/{user_id} for a particular resource(user with user_id)。

/users/ is misleading and often error prone as it seems to suggest you are operating on user with user_id None or ""