0

I am designing the rest apis that represent a file system.

File system support 3 functions

  1. mkdir(path)
  2. createFile(path, content) -> create if not exist and replace if exist.
  3. readFile(path)

Here is the REST API, I am thinking of designing what do you guys think of it ?

1. mkdir
POST v1/file-system/directories
BODY {
      "path" : "???"
     }
RESPONSE
     {
       "id" : "",
       "path" "",
       "files": [...] // this will contain info on files or directories under this directory
     }
2. createFile
PUT v1/file-system/files
BODY {
      "path" : "???"
      "content": ""
     }
RESPONSE
     {
       "id" : "",
       "content": ""
       "path" ""
     }
3. read
GET v1/file-system/files/{file-path} or
GET v1/file-system/files?file-path={file-path}
RESPONSE
     {
       "id" : "",
       "content": ""
       "path" ""
     }

Can you guys tell me if these API'S are correct representation for these function.

Few questions

  1. For GET API, shall I specify the path as path variable or query param ? If path then how will the backend differentiate between url path and file path. e.g. v1/file-system/files/a/b/c.txt
  2. Since create file can either create a file or replace the content of existing file, is it safe to use PUT ?
  3. For POST and PUT, do we specify path as path variable ?
tutorguru
  • 31
  • 3
  • 1. Is opinionated, please see [this post](https://stackoverflow.com/questions/30967822/when-do-i-use-path-params-vs-query-params-in-a-restful-api) 2-3. Diference between POST and PUT well described [here](https://stackoverflow.com/questions/630453/what-is-the-difference-between-post-and-put-in-http?noredirect=1&lq=1) – ivanjermakov Nov 15 '21 at 08:03
  • Why would you return a list of files after an `mkdir`? – Maurice Perry Nov 15 '21 at 09:23

1 Answers1

0

You have to understand that each request method (GET, POST, PUT...) has its own convention, but they do not differentiate a lot from each other.

For example, you could use POST to update something and not PATCH or so on.

At the end of the day, both methods, receive data in the body of the request and do something with it (or not).

Regarding your questions:

  1. I would avoid sending a path as a query param. Send your data through the request body. That way you have a JSON and you don't have to care about specific encoding and character escaping for the URL.
  2. Again, it is very safe since they only change because of the convention. We mostly use POST to create new data and PUT to create and replace data if it exists. Check this for more info.
  3. Again, avoid putting paths as query params. Insert them into the body as JSON.

Read this article to learn more about HTTP Methods.

Renis1235
  • 4,116
  • 3
  • 15
  • 27