Backend - API Convention: Data Structure, Error Handling, Response Codes

[rburaksaritas]

Issue Description

To maintain consistency, clarity, and efficient debugging across our services, we need to standardize the API convention. This documentation will detail the preferred data structures, methodologies for error handling, and guidelines on response codes.

Deadline of the Issue

17.10.2023

Reviewer

Begüm Arslan

[rburaksaritas]

@mehmetkuzu did a great job to start @ https://github.com/bounswe/bounswe2023group2/wiki/API-conventions.
I added the URI naming convensions as discussed in the Backend team meeting.
Also modified the general categorization & heading hiearchy structure etc.

[mehmetkuzu]

@mehmetkuzu did a great job to start @ https://github.com/bounswe/bounswe2023group2/wiki/API-conventions. I added the URI naming convensions as discussed in the Backend team meeting. Also modified the general categorization & heading hiearchy structure etc.

Thanks. Good job.

Just one point:

Incorrect	Correct
POST /createUser	POST /users
PUT /updateUser/1	PUT /users/1
DELETE /deleteUser/1	DELETE /users/1

This probably is a common practice. But are you sure? Why not PUT /users/create or PUT /user/create ? These numbers (1). Are they really the best way?

(Just asking to learn.)

[rburaksaritas]

@mehmetkuzu did a great job to start @ https://github.com/bounswe/bounswe2023group2/wiki/API-conventions. I added the URI naming convensions as discussed in the Backend team meeting. Also modified the general categorization & heading hiearchy structure etc.

Thanks. Good job.

Just one point:

Incorrect Correct
POST /createUser POST /users
PUT /updateUser/1 PUT /users/1
DELETE /deleteUser/1 DELETE /users/1
This probably is a common practice. But are you sure? Why not PUT /users/create or PUT /user/create ? These numbers (1). Are they really the best way?

(Just asking to learn.)

As far as i know, for example, POST is only used to create an entity, so URI like POST users/create/ is redundant, and basically means the same thing as POST users/ . Simlarly, PUT is only used to update an entity, therefore PUT users/id mean the same thing as PUT users/update/id defaultly.

[mehmetkuzu]

Thanks. That tells.

But should we write:
PUT /users/{user_id}
instead of
PUT /users/1

[rburaksaritas]

Thanks. That tells.

But should we write: PUT /users/{user_id} instead of PUT /users/1

yes, 1 is just an example id.

[azizamankenova]

Thanks for your efforts!
I wanted to ask if we need to include the ID of the newly created item as a result of the post request 3.1.3 POST - Create New Item (HTTP 201)?

[mehmetkuzu]

Thanks for your efforts! I wanted to ask if we need to include the ID of the newly created item as a result of the post request 3.1.3 POST - Create New Item (HTTP 201)?

You are right. The message structure also should be revised. I will check that now.

[mehmetkuzu]

Can we close this one? (We can always update the document during the actual work)

[bgmrsln]

Seems great! Closing the issue.