Take decisions before launching in public
## Version

Should we integrate a version in the path or domain, to help with future breaking changes?

Three options:
1. domain based: https://v1.datasets-server.huggingface.co
2. path based: https://datasets-server.huggingface.co/v1/
3. no version (current): https://datasets-server.huggingface.co

I think 3 is OK. Not having a version means we have to try to make everything backward-compatible, which is not a bad idea. If it's really needed, we can switch to 1 or 2 afterward. Also: having a version means that if we do breaking changes, we should maintain at least two versions in parallel...

## Envelop

A common pattern is to always return a JSON object with `data` or `error`. This way, we know that we can always consume the API with:

```js
const {data, error} = fetch(...)
```

and test for the existence of data, or error. Otherwise, every endpoint might have different behavior. Also: it's useful to have the envelop when looking at the response without knowing the HTTP status code (eg: in our cache)

Options:
1. no envelop (current): the client must rely on the HTTP status code to get the type of response (error or OK)
2. envelop: we need to migrate all the endpoints, to add an intermediate "data" or "error" field.

## HTTP status codes

We currently only use 200, 400, and 500 for simplicity. We might want to return alternative status codes such as 404 (not found), or 401/403 (when we will protect some endpoints).

Options:
1. only use 200, 400, 500 (current)
2. add more status codes, like 404, 401, 403

I think it's OK to stay with 300, 400, and 500, and let the client use the details of the response to figure out what failed.

## Error codes

Currently, the errors have a "message" field, and optionally three more fields: "cause_exception", "cause_message" and "cause_traceback". We could add a "code" field, such as "NOT_STREAMABLE", to make it more reliable for the client to implement logic based on the type of error (indeed: the message is a long string that might be updated later. A short code should be more reliable). Also: having an error code could counterbalance the lack of detailed HTTP status codes (see the previous point).

Internally, having codes could help indirect the messages to a dictionary, and it would help to catalog all the possible types of errors in the same place.

Options:
1. no "code" field (current)
2. add a "code" field, such as "NOT_STREAMABLE"

I'm in favor of adding such a short code.

## Case

The endpoints with several words are currently using "spinal-case", eg "/first-rows". An alternative is to use "snake_case", eg "/first_rows". Nothing important here.

Options:
1. "/spinal-case" (current)
2. "/snake_case"

I think it's not important, we can keep with spinal-case, and it's coherent with Hub API: https://huggingface.co/docs/hub/api




Take decisions before launching in public: ## Version

Should we integrate a version in the path or domain, to help with future breaking changes?

Three options:
1. domain based: https://v1.datasets-server.huggingface.co
2. path based: https://datasets-server.huggingface.co/v1/
3. no version (current): https://datasets-server.huggingface.co

I think 3 is OK. Not having a version means we have to try to make everything backward-compatible, which is not a bad idea. If it's really needed, we can switch to 1 or 2 afterward. Also: having a version means that if we do breaking changes, we should maintain at least two versions in parallel...

## Envelop

A common pattern is to always return a JSON object with `data` or `error`. This way, we know that we can always consume the API with:

```js
const {data, error} = fetch(...)
```

and test for the existence of data, or error. Otherwise, every endpoint might have different behavior. Also: it's useful to have the envelop when looking at the response without knowing the HTTP status code (eg: in our cache)

Options:
1. no envelop (current): the client must rely on the HTTP status code to get the type of response (error or OK)
2. envelop: we need to migrate all the endpoints, to add an intermediate "data" or "error" field.

## HTTP status codes

We currently only use 200, 400, and 500 for simplicity. We might want to return alternative status codes such as 404 (not found), or 401/403 (when we will protect some endpoints).

Options:
1. only use 200, 400, 500 (current)
2. add more status codes, like 404, 401, 403

I think it's OK to stay with 300, 400, and 500, and let the client use the details of the response to figure out what failed.

## Error codes

Currently, the errors have a "message" field, and optionally three more fields: "cause_exception", "cause_message" and "cause_traceback". We could add a "code" field, such as "NOT_STREAMABLE", to make it more reliable for the client to implement logic based on the type of error (indeed: the message is a long string that might be updated later. A short code should be more reliable). Also: having an error code could counterbalance the lack of detailed HTTP status codes (see the previous point).

Internally, having codes could help indirect the messages to a dictionary, and it would help to catalog all the possible types of errors in the same place.

Options:
1. no "code" field (current)
2. add a "code" field, such as "NOT_STREAMABLE"

I'm in favor of adding such a short code.

## Case

The endpoints with several words are currently using "spinal-case", eg "/first-rows". An alternative is to use "snake_case", eg "/first_rows". Nothing important here.

Options:
1. "/spinal-case" (current)
2. "/snake_case"

I think it's not important, we can keep with spinal-case, and it's coherent with Hub API: https://huggingface.co/docs/hub/api



