5 added 7 characters in body
source | link

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

IUpdate: I want to ask the community about best practices and experiences here. Thanks for your ideas. Even - especially when Dropbox and Google Drive both use two different approaches (see first answer and comments below): DropBox is using the path while Google Drive is using IDs.

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas. Even when Dropbox and Google Drive both use two different approaches (see first answer and comments below): DropBox is using the path while Google Drive is using IDs.

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

Update: I want to ask the community about best practices and experiences here - especially when Dropbox and Google Drive both use two different approaches (see first answer and comments below): DropBox is using the path while Google Drive is using IDs.

4 added 44 characters in body
source | link

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas.

Update Even when Dropbox and Google Drive both use two different approaches (see first answer and comments below): DropBox is using the path while Google Drive is using IDs. Interestingly, Dropbox and Google Drive use two different approaches (see first answer and comments below).

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas.

Update: Interestingly, Dropbox and Google Drive use two different approaches (see first answer and comments below).

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas. Even when Dropbox and Google Drive both use two different approaches (see first answer and comments below): DropBox is using the path while Google Drive is using IDs.

3 added 123 characters in body
source | link

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas.

Update: Interestingly, Dropbox and Google Drive use two different approaches (see first answer and comments below).

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas.

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/" in it), and not something like an artificial id such as a UUID.

Naturally, a user would identify a file by it's path:

/path/to/file.txt

Unfortunately, this clashes with common, good API design.

This would work:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

However, other methods you would like to have, will become a bit problematic:

Retrieving a file list of a folder: GET /api/v1/folders/<path/to/folder>/files

My thoughts so far:

  • avoid unique identifiers with "/" in it entirely, and use an artificial UUID (such as Alfresco is using NodeId / NodeRefs). This would add another layer of abstraction to it, where a unique id is just not very natural from a business domain perspective
  • don't use the identifier in the url path but in a parameter (against good API design patterns)
  • (requesting the API users to replace the / with another character is of course also not an option)

Of course, files and folders as we know it from a file system, are naturally identified by it's path. In that particular case, one could argue that if someone wants to use the path as the identifier, than the correct way for doing:

Retrieving a file: GET /api/v1/files/<path/to/file.txt>

would actually be:

Retrieving a file: GET /api/v1/folders/<path>/folders/<to>/files/<file.txt>

if we want to be really correct here.

I want to ask the community about best practices and experiences here. Thanks for your ideas.

Update: Interestingly, Dropbox and Google Drive use two different approaches (see first answer and comments below).

2 added 444 characters in body
source | link
1
source | link