Skip to content

Instantly share code, notes, and snippets.

@stavarengo

stavarengo/Auction_API.md

Last active June 11, 2019 15:46
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save stavarengo/0ab4ec1ee4058fe2287f6fbd04503b11 to your computer and use it in GitHub Desktop.
Save stavarengo/0ab4ec1ee4058fe2287f6fbd04503b11 to your computer and use it in GitHub Desktop.
Download ZIP
Example of API documentation
Raw
Auction_API.md

Auction API

The Auction API allows you to manipulate lots, bids in an auction. The operations you can do, through the API, are:

Layout of The Error Response

All endpoints, when end in failure, respond with a JSON trying to describe why the error happens (for example, it would fail if you forget to send a required parameter). The following is the JSON used to represent an error response.

{
  /**
   * This attribute will always be `true`
   * @type boolean
   */
  "error": true,
  
  /**
   * An string containing more details about the error.
   * @type string
   */
  "detail": "Missing the 'weight' value."
}

POST /lot

Create a new lot.

URL params

None

Data params

It expect that the request body contains a JSON with the following layout (all values are required):

{
  /**
   * The ID of the seller who is creating the lot.
   * @type integer
   * @required true
   */
  "seller": 899,
  /**
   * Weight of the lot in KG.
   * @type float
   * @required true
   */
  "weight": 1500,
  /**
   * Origin country of the lot.
   * @type string
   * @required true
   */
  "country": "Costa Rica",
  /**
   * Date of harvesting.
   * It must be in the following format: YYYY-MM-DD
   * @type string
   * @required true
   */
  "harvesting": "2018-07-27",
  /**
   * Cultivar name.
   * @type string
   * @required true
   */
  "cultivar": "Red Dacca"
}

Curl example

$ curl -X POST 'http://127.0.0.1/lot' --data-binary '{"seller": 899, "weight": 1500, "country": "Costa Rica", "harvesting": "2018-07-27", "cultivar": "Red Dacca"}'

Success Response

201 - Created

It means the lot was successfully created. The response body will have the ID of the created lot.

Response Body

{"lotId": 12}

Error Response

All error responses will contain a body with The Error Response Layout.

  • 422 - Unprocessable Entity: If the weight is less then 1000.
  • 422 - Unprocessable Entity: When any required data is missing.
  • 422 - Unprocessable Entity: If the harvesting date is in invalid format.
  • 405 - Method Not Allowed: If you use a method no supported by this endpoint.
  • 400 - Bad Request: If the request could not be processed because of an unexpected reason.

PUT /lot/:LOT_ID

Changes information of the lot.

URL params

  • :LOT_ID: ID of the lot you want to change.
    Required: true.
    Type: Integer.

Data params

It expect that the request body contains a JSON with the same layout described in the POST /lot Data Params, but you do not need to pass all the parameters again. You can send only the information you want to change.

Curl example

$ curl -X PUT 'http://127.0.0.1/lot/12' --data-binary '{"harvesting": "2018-06-14"}'

Success Response

200 - OK

It means that the lot was successfully updated.

Response Body The response will contain the whole lot information.

{"seller": 899, "weight": 1500, "country": "Costa Rica", "harvesting": "2018-06-14", "cultivar": "Red Dacca"}

Error Response

All error responses will contain a body with The Error Response Layout.

  • 404 - Not Found: If there is no lot with the ID you provide in the :LOT_ID parameter.
  • 422 - Unprocessable Entity: If the weight is less then 1000.
  • 422 - Unprocessable Entity: When any required data is missing.
  • 422 - Unprocessable Entity: If the harvesting date is in invalid format.
  • 405 - Method Not Allowed: If you use a method no supported by this endpoint.
  • 400 - Bad Request: If the request could not be processed because of an unexpected reason.

POST /auction/:LOT_ID

Starts the auction of a lot.

URL params

  • :LOT_ID: ID of the lot you want to start the auction.
    Required: true.
    Type: Integer.

Data params

It expect that the request body contains a JSON with the following layout (all values are required):

{
  /**
   * The initial price per KG of the lot in the auction.
   * @type float
   * @required true
   */
  "initialPrice": 1.2,
  /**
   * Determines how many hours the auction will accept bids.
   * @type integer
   * @required true
   */
  "durationInHours": 24
}

Curl example

$ curl -X POST 'http://127.0.0.1/auction/12' --data-binary '{"initialPrice": 1.2, "durationInHours": 24}'

Success Response

200 - OK

It means the auction was started for your lot. The response body will have the ID of the created auction.

Response Body

{"auctionId": 7}

Error Response

All error responses will contain a body with The Error Response Layout.

  • 422 - Unprocessable Entity: If the initialPrice is less then or equals to zero.
  • 422 - Unprocessable Entity: If the durationInHours is less then one.
  • 422 - Unprocessable Entity: When any required data is missing.
  • 404 - Not Found: If there is no lot with the ID you provide in the :LOT_ID parameter.
  • 405 - Method Not Allowed: If you use a method no supported by this endpoint.
  • 400 - Bad Request: If the request could not be processed because of an unexpected reason.

POST /bid/:LOT_ID

Bids on a lot.

URL params

  • :LOT_ID: ID of the lot you want to bid.
    Required: true.
    Type: Integer.

Data params

It expect that the request body contains a JSON with the following layout (all values are required):

{
  /**
   * The value of or bid.
   * @type float
   * @required true
   */
  "bid": 1.35
}

Curl example

$ curl -X POST 'http://127.0.0.1/bid/12' --data-binary '{"bid": 1.35}'

Success Response

200 - OK

It means your bid is registered. The response body will have the ID of the auction this lot belongs to.

Response Body

{"auctionId": 7}

Error Response

All error responses will contain a body with The Error Response Layout.

  • 422 - Unprocessable Entity: If the bid is less then or equals to zero.
  • 422 - Unprocessable Entity: When any required data is missing.
  • 404 - Not Found: If there is no lot with the ID you provide in the :LOT_ID parameter.
  • 405 - Method Not Allowed: If you use a method no supported by this endpoint.
  • 400 - Bad Request: If the request could not be processed because of an unexpected reason.

GET /bid/:LOT_ID[?page=integer&page-size=integer]

List the bids of a lot.

URL params

  • :LOT_ID: ID of the lot you want get the list of its bids.
    Required: true.
    Type: Integer.
  • page: The page of the list. Required: false.
    Default: 1
    Type: Integer.
  • page-size: Home many items per page. Required: false.
    Default: 20
    Type: Integer.

Data params

None

Curl example

$ curl -X GET 'http://127.0.0.1/bid/12'

Success Response

200 - OK

In this case you will get the following response body:

Response Body

{
    /**
     * List of the bids.
     * @type Object[]
     */
    "bids": [
        {
            /**
             * The date and time of the bid in the ISO 8601 standard.
             * @see https://en.wikipedia.org/wiki/ISO_8601
             * @type string
             */
            "date": "2019-06-05T16:25:02-0000",
            /**
             * How much was offered for your lot.
             * @type float
             */
            "value": 1.35,
            /**
             * The user who did this bid.
             * @type Object
             */
            "user": {
                /**
                * The name of the user who did this bid.
                 * @type string
                 */
                "fullName": "Rafael Stavarengo",
                /**
                 * The URL of the user who did this bid.
                 * @type string
                 */
                "picture": "https://www.gravatar.com/avatar/4879e9ac64413ff79bb42f2a72b56830?&s=300"
            }
        }
    ],
    /**
     * How may bids your lot received.
     * @type integer
     */
    "bidsCount": 1,
    /**
     * The current page this list belongs.
     * @type integer
     */
    "page": 1,
    /**
     * The number of the next page, or NULL if there is no more pages.
     * @type integer|null
     */
    "nextPage": null
}

Error Response

All error responses will contain a body with The Error Response Layout.

  • 404 - Not Found: If there is no lot with the ID you provide in the :LOT_ID parameter.
  • 405 - Method Not Allowed: If you use a method no supported by this endpoint.
  • 400 - Bad Request: If the request could not be processed because of an unexpected reason.

DELETE /lot/:LOT_ID

Delete a lot.

URL params

  • :LOT_ID: ID of the lot you want to delete.
    Required: true.
    Type: Integer.

Data params

None

Curl example

$ curl -X DELETE 'http://127.0.0.1/lot/12'

Success Response

204 - No Content

It means that the lot was deleted. You will get this code even if the lot :LOT_ID does not exit.

Response Body

None

Error Response

All error responses will contain a body with The Error Response Layout.

  • 405 - Method Not Allowed: If you use a method no supported by this endpoint.
  • 400 - Bad Request: If the request could not be processed because of an unexpected reason.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment