From a7c884396760645cd80e90dfc4188f740197ed76 Mon Sep 17 00:00:00 2001 From: Sujan Midatani Date: Sat, 11 May 2024 23:02:34 +0530 Subject: [PATCH 1/5] added API methods to the documentation --- contrib/api-development/api-methods.md | 27 ++++++++++++++++++++++++++ contrib/api-development/index.md | 2 +- 2 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 contrib/api-development/api-methods.md diff --git a/contrib/api-development/api-methods.md b/contrib/api-development/api-methods.md new file mode 100644 index 0000000..8c66919 --- /dev/null +++ b/contrib/api-development/api-methods.md @@ -0,0 +1,27 @@ +## API Methods + +- **GET**: + - The GET method is used to retrieve data from a specified resource. + - It is a safe and idempotent method, meaning that it should not have any side effects and can be called multiple times without changing the result. + - Use the GET method when you want to retrieve information from the server. + +- **POST**: + - The POST method is used to submit data to be processed to a specified resource. + - It is not idempotent, meaning that calling the same POST request multiple times may result in different outcomes. + - Use the POST method when you want to create a new resource on the server. + +- **PUT**: + - The PUT method is used to update a specified resource with new data. + - It is idempotent, meaning that calling the same PUT request multiple times should have the same effect as calling it once. + - Use the PUT method when you want to update an existing resource on the server. + +- **PATCH**: + - The PATCH method is used to apply partial modifications to a resource. + - It is not idempotent, meaning that calling the same PATCH request multiple times may result in different outcomes. + - Use the PATCH method when you want to update a resource with partial data. + +- **DELETE**: + - The DELETE method is used to delete a specified resource. + - It is idempotent, meaning that calling the same DELETE request multiple times should have the same effect as calling it once. + - Use the DELETE method when you want to remove a resource from the server. + diff --git a/contrib/api-development/index.md b/contrib/api-development/index.md index 82596a2..75c702a 100644 --- a/contrib/api-development/index.md +++ b/contrib/api-development/index.md @@ -1,3 +1,3 @@ # List of sections -- [Section title](filename.md) +- [API Methods](api-methods.md) From d4c8ab4d49caa7549ef0ce77c665e72bb768b94f Mon Sep 17 00:00:00 2001 From: Sujan Midatani Date: Sat, 11 May 2024 23:24:31 +0530 Subject: [PATCH 2/5] added additional API methods to the documentation --- contrib/api-development/api-methods.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/contrib/api-development/api-methods.md b/contrib/api-development/api-methods.md index 8c66919..61e10d7 100644 --- a/contrib/api-development/api-methods.md +++ b/contrib/api-development/api-methods.md @@ -25,3 +25,23 @@ - It is idempotent, meaning that calling the same DELETE request multiple times should have the same effect as calling it once. - Use the DELETE method when you want to remove a resource from the server. +- **OPTIONS**: + - The OPTIONS method is used to describe the communication options for the target resource. + - It is idempotent, meaning that calling the same OPTIONS request multiple times should have the same effect as calling it once. + - Use the OPTIONS method when you want to retrieve the communication options for a resource. + +- **HEAD**: + - The HEAD method is similar to the GET method, but it only retrieves the headers of the response without the body. + - It is idempotent, meaning that calling the same HEAD request multiple times should have the same effect as calling it once. + - Use the HEAD method when you want to check the headers of a resource without retrieving the body. + +- **TRACE**: + - The TRACE method is used to test the connectivity between the client and the server. + - It is idempotent, meaning that calling the same TRACE request multiple times should have the same effect as calling it once. + - Use the TRACE method when you want to test the connectivity between the client and the server. + +- **CONNECT**: + - The CONNECT method is used to establish a tunnel to the server using a proxy. + - It is not idempotent, meaning that calling the same CONNECT request multiple times may result in different outcomes. + - Use the CONNECT method when you want to establish a tunnel to the server using a proxy. + From 7ad18bd08e99f448c7671e0bc8c295928e5c62cd Mon Sep 17 00:00:00 2001 From: Sujan Midatani Date: Sat, 11 May 2024 23:59:31 +0530 Subject: [PATCH 3/5] added tabular explaination of API methods to the documentation --- contrib/api-development/api-methods.md | 34 ++++++++++++-------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/contrib/api-development/api-methods.md b/contrib/api-development/api-methods.md index 61e10d7..8de9184 100644 --- a/contrib/api-development/api-methods.md +++ b/contrib/api-development/api-methods.md @@ -1,47 +1,43 @@ -## API Methods +# API Methods + +| Method | Summary | CRUD | Accepts Request Body | Idempotent | Safe | +|---------|----------------------------------------------------------|--------|-----------------------|------------|------| +| GET | To fetch a single resource or group of resources | Read | No | Yes | Yes | +| PUT | To update an entire resource in one go | Update | Yes | Yes | No | +| POST | To create a new resource | Create | Yes | No | No | +| PATCH | To partially update a resource | Update | Yes | No | No | +| DELETE | To delete a resource | Delete | No | Yes | No | +| OPTIONS | To get information on permitted operations | Read | No | Yes | Yes | +| HEAD | To get metadata of the endpoint | Read | No | Yes | Yes | +| TRACE | For diagnosing purposes | Read | No | Yes | Yes | +| CONNECT | To make the two-way connection between the client and the resource | - | No | No | No | + +## Method Details: - **GET**: - The GET method is used to retrieve data from a specified resource. - - It is a safe and idempotent method, meaning that it should not have any side effects and can be called multiple times without changing the result. - - Use the GET method when you want to retrieve information from the server. - **POST**: - The POST method is used to submit data to be processed to a specified resource. - - It is not idempotent, meaning that calling the same POST request multiple times may result in different outcomes. - - Use the POST method when you want to create a new resource on the server. - **PUT**: - The PUT method is used to update a specified resource with new data. - - It is idempotent, meaning that calling the same PUT request multiple times should have the same effect as calling it once. - - Use the PUT method when you want to update an existing resource on the server. - **PATCH**: - The PATCH method is used to apply partial modifications to a resource. - - It is not idempotent, meaning that calling the same PATCH request multiple times may result in different outcomes. - - Use the PATCH method when you want to update a resource with partial data. - **DELETE**: - The DELETE method is used to delete a specified resource. - - It is idempotent, meaning that calling the same DELETE request multiple times should have the same effect as calling it once. - - Use the DELETE method when you want to remove a resource from the server. - **OPTIONS**: - The OPTIONS method is used to describe the communication options for the target resource. - - It is idempotent, meaning that calling the same OPTIONS request multiple times should have the same effect as calling it once. - - Use the OPTIONS method when you want to retrieve the communication options for a resource. - **HEAD**: - The HEAD method is similar to the GET method, but it only retrieves the headers of the response without the body. - - It is idempotent, meaning that calling the same HEAD request multiple times should have the same effect as calling it once. - - Use the HEAD method when you want to check the headers of a resource without retrieving the body. - **TRACE**: - The TRACE method is used to test the connectivity between the client and the server. - - It is idempotent, meaning that calling the same TRACE request multiple times should have the same effect as calling it once. - - Use the TRACE method when you want to test the connectivity between the client and the server. - **CONNECT**: - The CONNECT method is used to establish a tunnel to the server using a proxy. - - It is not idempotent, meaning that calling the same CONNECT request multiple times may result in different outcomes. - - Use the CONNECT method when you want to establish a tunnel to the server using a proxy. From 2a3d288a72edb7b6a87ed32da0b7c1256eff8ea4 Mon Sep 17 00:00:00 2001 From: Sujan Midatani Date: Sun, 12 May 2024 00:10:48 +0530 Subject: [PATCH 4/5] added extra details to the table for explaination of API methods to the documentation --- contrib/api-development/api-methods.md | 41 +++++++++++++------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/contrib/api-development/api-methods.md b/contrib/api-development/api-methods.md index 8de9184..de3228a 100644 --- a/contrib/api-development/api-methods.md +++ b/contrib/api-development/api-methods.md @@ -1,43 +1,42 @@ # API Methods -| Method | Summary | CRUD | Accepts Request Body | Idempotent | Safe | -|---------|----------------------------------------------------------|--------|-----------------------|------------|------| -| GET | To fetch a single resource or group of resources | Read | No | Yes | Yes | -| PUT | To update an entire resource in one go | Update | Yes | Yes | No | -| POST | To create a new resource | Create | Yes | No | No | -| PATCH | To partially update a resource | Update | Yes | No | No | -| DELETE | To delete a resource | Delete | No | Yes | No | -| OPTIONS | To get information on permitted operations | Read | No | Yes | Yes | -| HEAD | To get metadata of the endpoint | Read | No | Yes | Yes | -| TRACE | For diagnosing purposes | Read | No | Yes | Yes | -| CONNECT | To make the two-way connection between the client and the resource | - | No | No | No | +| Method | Summary | CRUD | Accepts Request Body | Idempotent | Safe | Response Body | +|---------|----------------------------------------------------------|--------|-----------------------|------------|------|---------------| +| GET | To fetch a single resource or group of resources | Read | No | Yes | Yes | Yes | +| PUT | To update an entire resource in one go | Update | Yes | Yes | No | Yes | +| POST | To create a new resource | Create | Yes | No | No | Yes | +| PATCH | To partially update a resource | Update | Yes | No | No | Yes | +| DELETE | To delete a resource | Delete | No | Yes | No | No | +| OPTIONS | To get information on permitted operations | Read | No | Yes | Yes | Yes | +| HEAD | To get metadata of the endpoint | Read | No | Yes | Yes | No | +| TRACE | For diagnosing purposes | Read | No | Yes | Yes | No | +| CONNECT | To make the two-way connection between the client and the resource | - | No | No | No | No | ## Method Details: - **GET**: - - The GET method is used to retrieve data from a specified resource. + - The GET method is used to retrieve data from a specified resource. It does not typically alter the state of the resource and is safe and idempotent. It can accept query parameters in the URL to filter or sort the results. A response body is returned with the requested data. - **POST**: - - The POST method is used to submit data to be processed to a specified resource. + - The POST method is used to submit data to be processed to a specified resource. It is commonly used for creating new resources, and it may or may not require a request body containing the data to be created. It is not idempotent nor safe. A response body is returned with the newly created resource's details. - **PUT**: - - The PUT method is used to update a specified resource with new data. + - The PUT method is used to update a specified resource with new data. It typically requires a request body containing the complete representation of the resource to be updated. It is idempotent and not safe. A response body is returned with the updated resource's details. - **PATCH**: - - The PATCH method is used to apply partial modifications to a resource. + - The PATCH method is used to apply partial modifications to a resource. It typically requires a request body containing the specific changes to be made. It is not idempotent nor safe. A response body is returned with the updated resource's details. - **DELETE**: - - The DELETE method is used to delete a specified resource. + - The DELETE method is used to delete a specified resource. It does not typically require a request body, as the resource to be deleted is identified in the request URI. It is idempotent but not safe. No response body is returned. - **OPTIONS**: - - The OPTIONS method is used to describe the communication options for the target resource. + - The OPTIONS method is used to describe the communication options for the target resource. It does not typically require a request body and is safe and idempotent. A response body is returned with information about the supported HTTP methods and other metadata. - **HEAD**: - - The HEAD method is similar to the GET method, but it only retrieves the headers of the response without the body. + - The HEAD method is similar to the GET method, but it only retrieves the headers of the response without the body. It does not typically require a request body and is safe and idempotent. - **TRACE**: - - The TRACE method is used to test the connectivity between the client and the server. + - The TRACE method is used to test the connectivity between the client and the server. It does not typically require a request body and is safe and idempotent. - **CONNECT**: - - The CONNECT method is used to establish a tunnel to the server using a proxy. - + - The CONNECT method is used to establish a tunnel to the server using a proxy. It does not typically require a request body and is neither safe nor idempotent. From 237a00cdbfaab63481a5390fb92a2040ccc95fdd Mon Sep 17 00:00:00 2001 From: Sujan Midatani Date: Sun, 12 May 2024 00:19:57 +0530 Subject: [PATCH 5/5] added DEFINITIONS FOR ATTRIBUTES of API methods to the documentation --- contrib/api-development/api-methods.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/contrib/api-development/api-methods.md b/contrib/api-development/api-methods.md index de3228a..ea41979 100644 --- a/contrib/api-development/api-methods.md +++ b/contrib/api-development/api-methods.md @@ -40,3 +40,17 @@ - **CONNECT**: - The CONNECT method is used to establish a tunnel to the server using a proxy. It does not typically require a request body and is neither safe nor idempotent. + +### Definitions: + +- **CRUD**: + - CRUD stands for Create, Read, Update, and Delete, representing the four basic functions of persistent storage. These operations are commonly used in database and RESTful API designs. + +- **Accepts Request Body**: + - Indicates whether the HTTP method typically accepts a request body containing data to be processed or modified. If yes, the method may require the client to include data in the request body. + +- **Idempotent**: + - An idempotent operation means that making the same request multiple times will produce the same result as making it once. In the context of HTTP methods, an idempotent method does not change the server state after multiple identical requests. + +- **Safe**: + - A safe operation does not modify the state of the server or its resources. It only retrieves data without causing any side effects. Safe methods are typically used for read-only operations. \ No newline at end of file