suhas-karanth/API.md

## API.md

      
    Raw
  

              API.md
            
          
    Title

<Additional information about your API call. Try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple).>


URL
<The URL Structure (path only, no root url)>


Method:
<The request type>
GET | POST | DELETE | PUT


  **URL Params**
<_If URL params exist, specify them in accordance with name mentioned in URL section. Separate into optional and required. Document data constraints._> 


Required:

id=[integer]


Optional:

photo_id=[alphanumeric]


  **Data Params**
<_If making a post request, what should the body payload look like? URL Params rules apply here too._>


  **Sample Call**
<_Just a sample call to your endpoint in a runnable format ($.ajax call or a curl request) - this makes life easier and more predictable._> 


  **Success Response**
<_What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect!_>

Code: 200 

Content:
{ "id" : 12 }


  **Error Response**
<_Most endpoints will have many ways they can fail. From unauthorized access, to wrongful parameters etc. All of those should be liste d here. It might seem repetitive, but it helps prevent assumptions from being made where they should be._>

Code: 401 UNAUTHORIZED 

Content:
{ "error" : "Log in" }


OR

Code: 422 UNPROCESSABLE ENTRY 

Content:
{ "error" : "Email Invalid" }


  **Notes**
<_This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here._> 


## EXAMPLE.md

      
    Raw
  

              EXAMPLE.md
            
          
    Cancel Orders

API for cancellation of order. Order can only be cancelled if the products have not been shipped.
Cancellation can be for the entire order or specific item in the order


URL
/control/cancelOrderOrOrderItem


Method:
POST


    **URL/POST Params**
- **Required:**
  + `orderId=[alphanumeric]` *Order id to be canceled*
  + `refundType=[string]` - `"storecredit"` or `"manualrefund"` *Method of order amount refund*

Optional:

orderItemSeqId=[string] Order item sequence id of order item to be cancelled
cancelQuantity=[number] Specific number of quantity to be cancelled


    **Sample Call**
```bash
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'orderId=BY861380&refundType=storecredit' \
  "https://www.example.com/control/cancelOrderOrOrderItem"
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" 

-d 'orderId=BY861325&refundType=storecredit&orderItemSeqId=00002&cancelQuantity=1' 

"https://www.example.com/control/cancelOrderOrOrderItem"
</details>

<details>
    <summary>**Success Response**</summary>
* **Code:** 200 OK <br />
  **Content:**
  ```json
  {
    "result": "success",
    "cancellationSucess": "Y",
    "refundType": "storecredit",
    "comments": "Order cancelled successfully"
  }


OR

Code: 200 OK 

Content:
{
  "result": "success",
  "cancellationSucess": "Y",
  "refundType": "storecredit",
  "comments": "Order item cancelled successfully"
}


    **Error Response**
* **Code:** 200 OK 

  **Reason:** User not logged in

  **Content:**
  ```json
  {
    "result": "error",
    "ERR_CODE": "1002",
    "message": "Unauthorised request. Please login with your credentials."
  }

OR

* **Code:** 200 OK <br />
**Reason:** If the order does not belong to the logged in user <br />
**Content:**
```json
{
  "errorMessage": "You do not have permission to change this order's status.",
  "result": "error",
  "cancellationSucess": "N",
  "comments": "Order could not be cancelled"
}


OR

Code: 200 OK 

Reason: If the order does not exist 

Content:
{
  "errorMessage": "Order not found with orderId [BY861380]",
  "result": "error",
  "cancellationSucess": "N",
  "comments": "Order could not be cancelled"
}


OR

Code: 200 OK 

Reason: Cancel quantity more than originally bought 

Content:
{
  "errorMessage": "Invalid cancel quantity; cannot cancel 2",
  "result": "error",
  "cancellationSucess": "N",
  "comments": "Order item could not be cancelled"
}


  **Notes**
  - This request can also be made with `GET` method using query parameters but this is not recommended.
  - Repeated calls to the endpoint with valid parameters will result in successful request. It will not indicate that the order was already cancelled.
  - Invalid item sequence id is not validated and request will be successful.