Skip to content

Latest commit

 

History

History
92 lines (62 loc) · 5.06 KB

API_DOC.md

File metadata and controls

92 lines (62 loc) · 5.06 KB

Cuttlink API

The base address of Cuttlink API is http://localhost:3000 (will change when the app is hosted).

Endpoints

/

  • GET /:urlCode

/shortn

  • POST /shortn

Requests

The services are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Cuttlink API uses appropriate HTTP verbs for each action:

METHOD ACTION
GET Fetch shortened link
POST Create and fetch shortened link

Rate Limiting

Rate Limiting enables Cuttlink API to share access bandwidth to its resources equally across all users.

Rate limiting is applied as per user based on the user's IP, and allows a maximum of 100 requests per 3 mins.

Note: If Cuttlink API returns status code 429, it means that you have sent too many requests. When this happens, check the Retry-After header, where you will see a number displayed. This is the number of seconds that you need to wait, before you try your request again.

Responses

Cuttlink API returns all response data as a JSON object.

Here is an example of a response from a successful request to shorten a long url:

{
  "status": 200,
  "message": {
    "long_url": "https://en.wikibooks.org/wiki/Windows_Batch_Scripting#Using_the_Windows_command_interpreter",
    "short_url": "http://localhost:3000/3ys5Wqq"
  }
}

Response Status Codes

Cuttlink API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

STATUS CODE DESCRIPTION
200 OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
400 Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information; see Error Schema.
404 Not Found - The requested url could not be found. This error can be due to a temporary or permanent condition.
413 Request Entity Too Large - The server is refusing to process a request because the request entity is larger than the server is willing or able to process. The server MAY close the connection to prevent the client from continuing the request.
429 Too Many Requests - Rate limiting has been applied.
500 Internal Server Error. You should never receive this error because our code catch them all … but if you get one, please report it to us through a Github Issue.

Error Schema

Cuttlink API uses one format to describe errors:

  • Regular Error Object

Regular Error Object

Apart from the response code, unsuccessful responses return a JSON object containing the following information:

Key Value Type Value Description
status integer The HTTP status code that is also returned in the response header. For further information, see Response Status Codes.
message string A short description of the cause of the error.

Here, for example is the error that occurs when trying to post an invalid link to be shortened:

$ curl -X POST -H "Content-Type: application/json" \
    -d '{"url": ""}' \
    http://localhost:3000/shortn

HTTP/1.1 400 Bad Request
{
  "status": 400,
  "message": "Missing URL parameter"
}