|
@@ -1,289 +0,0 @@
|
|
|
-
|
|
|
-# REST API documentation
|
|
|
-
|
|
|
-## Error management
|
|
|
-
|
|
|
-Statuses:
|
|
|
-
|
|
|
-* 400 -> controlled error
|
|
|
-* 401 -> authentication error
|
|
|
-* 500 -> unexpected error
|
|
|
-
|
|
|
-[TODO]
|
|
|
-
|
|
|
-## Authentication
|
|
|
-
|
|
|
-Once you have called to the authentication endpoint for the first time (see below) yopu will get an authentication token.
|
|
|
-
|
|
|
-You will have to send that token in the `X-Auth-Token` header on any later request or you will get an authentication error.
|
|
|
-
|
|
|
-## Language
|
|
|
-
|
|
|
-In order to set the application language, you have to pass it by using the `Accept-Language` header.
|
|
|
-
|
|
|
-If not provided or provided language is not supported, english (en_US) will be used.
|
|
|
-
|
|
|
-## Endpoints
|
|
|
-
|
|
|
-#### Authenticate
|
|
|
-
|
|
|
-**REQUEST**
|
|
|
-
|
|
|
-* `POST` -> `/rest/authenticate`
|
|
|
-* Params:
|
|
|
- * username: `string`
|
|
|
- * password: `string`
|
|
|
-
|
|
|
-**SUCCESS RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "token": "9f741eb0-33d7-4c56-b8f7-3719e9929946"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**ERROR RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "error": "INVALID_ARGUMENT",
|
|
|
- "message": "You have to provide both \"username\" and \"password\""
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Posible errors:
|
|
|
-
|
|
|
-* **INVALID_ARGUMENT**: Username or password were not provided.
|
|
|
-* **INVALID_CREDENTIALS**: Username or password are incorrect.
|
|
|
-
|
|
|
-
|
|
|
-#### Create shortcode
|
|
|
-
|
|
|
-**REQUEST**
|
|
|
-
|
|
|
-* `POST` -> `/rest/short-codes`
|
|
|
-* Params:
|
|
|
- * longUrl: `string` -> The URL to shorten
|
|
|
-* Headers:
|
|
|
- * X-Auth-Token: `string` -> The token provided in the authentication request
|
|
|
-
|
|
|
-**SUCCESS RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "longUrl": "https://www.facebook.com/something/something",
|
|
|
- "shortUrl": "https://doma.in/rY9Kr",
|
|
|
- "shortCode": "rY9Kr"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**ERROR RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "error": "INVALID_URL",
|
|
|
- "message": "Provided URL \"wfwef\" is invalid. Try with a different one."
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Posible errors:
|
|
|
-
|
|
|
-* **INVALID_ARGUMENT**: The longUrl was not provided.
|
|
|
-* **INVALID_URL**: Provided longUrl has an invalid format or does not resolve.
|
|
|
-* **UNKNOWN_ERROR**: Something unexpected happened.
|
|
|
-
|
|
|
-
|
|
|
-#### Resolve URL
|
|
|
-
|
|
|
-**REQUEST**
|
|
|
-
|
|
|
-* `GET` -> `/rest/short-codes/{shortCode}`
|
|
|
-* Route params:
|
|
|
- * shortCode: `string` -> The short code we want to resolve
|
|
|
-* Headers:
|
|
|
- * X-Auth-Token: `string` -> The token provided in the authentication request
|
|
|
-
|
|
|
-**SUCCESS RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "longUrl": "https://www.facebook.com/something/something"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**ERROR RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "error": "INVALID_SHORTCODE",
|
|
|
- "message": "Provided short code \"abc123\" has an invalid format"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Posible errors:
|
|
|
-
|
|
|
-* **INVALID_ARGUMENT**: No longUrl was found for provided shortCode.
|
|
|
-* **INVALID_SHORTCODE**: Provided shortCode does not match the character set used by the app to generate short codes.
|
|
|
-* **UNKNOWN_ERROR**: Something unexpected happened.
|
|
|
-
|
|
|
-
|
|
|
-#### List shortened URLs
|
|
|
-
|
|
|
-**REQUEST**
|
|
|
-
|
|
|
-* `GET` -> `/rest/short-codes`
|
|
|
-* Query params:
|
|
|
- * page: `integer` -> The page to list. Defaults to 1 if not provided.
|
|
|
-* Headers:
|
|
|
- * X-Auth-Token: `string` -> The token provided in the authentication request
|
|
|
-
|
|
|
-**SUCCESS RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "shortUrls": {
|
|
|
- "data": [
|
|
|
- {
|
|
|
- "shortCode": "abc123",
|
|
|
- "originalUrl": "http://www.alejandrocelaya.com",
|
|
|
- "dateCreated": "2016-04-30T18:01:47+0200",
|
|
|
- "visitsCount": 4
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "def456",
|
|
|
- "originalUrl": "http://www.alejandrocelaya.com/en",
|
|
|
- "dateCreated": "2016-04-30T18:03:43+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "ghi789",
|
|
|
- "originalUrl": "http://www.alejandrocelaya.com/es",
|
|
|
- "dateCreated": "2016-04-30T18:10:38+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "jkl987",
|
|
|
- "originalUrl": "http://www.alejandrocelaya.com/es/",
|
|
|
- "dateCreated": "2016-04-30T18:10:57+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "mno654",
|
|
|
- "originalUrl": "http://blog.alejandrocelaya.com/2016/04/09/improving-zend-service-manager-workflow-with-annotations/",
|
|
|
- "dateCreated": "2016-04-30T19:21:05+0200",
|
|
|
- "visitsCount": 1
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "pqr321",
|
|
|
- "originalUrl": "http://www.google.com",
|
|
|
- "dateCreated": "2016-05-01T11:19:53+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "stv159",
|
|
|
- "originalUrl": "http://www.acelaya.com",
|
|
|
- "dateCreated": "2016-06-12T17:49:21+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "wxy753",
|
|
|
- "originalUrl": "http://www.atomic-reader.com",
|
|
|
- "dateCreated": "2016-06-12T17:50:27+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "zab852",
|
|
|
- "originalUrl": "http://foo.com",
|
|
|
- "dateCreated": "2016-07-03T09:07:36+0200",
|
|
|
- "visitsCount": 0
|
|
|
- },
|
|
|
- {
|
|
|
- "shortCode": "cde963",
|
|
|
- "originalUrl": "https://www.facebook.com.com",
|
|
|
- "dateCreated": "2016-07-03T09:12:35+0200",
|
|
|
- "visitsCount": 0
|
|
|
- }
|
|
|
- ],
|
|
|
- "pagination": {
|
|
|
- "currentPage": 4,
|
|
|
- "pagesCount": 15
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**ERROR RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "error": "UNKNOWN_ERROR",
|
|
|
- "message": "Unexpected error occured"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Posible errors:
|
|
|
-
|
|
|
-* **UNKNOWN_ERROR**: Something unexpected happened.
|
|
|
-
|
|
|
-
|
|
|
-#### Get visits
|
|
|
-
|
|
|
-**REQUEST**
|
|
|
-
|
|
|
-* `GET` -> `/rest/short-codes/{shortCode}/visits`
|
|
|
-* Route params:
|
|
|
- * shortCode: `string` -> The shortCode from which we eant to get the visits.
|
|
|
-* Query params:
|
|
|
- * startDate: `string` -> If provided, only visits older that this date will be returned
|
|
|
- * endDate: `string` -> If provided, only visits newer that this date will be returned
|
|
|
-* Headers:
|
|
|
- * X-Auth-Token: `string` -> The token provided in the authentication request
|
|
|
-
|
|
|
-**SUCCESS RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "shortUrls": {
|
|
|
- "data": [
|
|
|
- {
|
|
|
- "referer": null,
|
|
|
- "date": "2016-06-18T09:32:22+0200",
|
|
|
- "remoteAddr": "127.0.0.1",
|
|
|
- "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
|
|
|
- },
|
|
|
- {
|
|
|
- "referer": null,
|
|
|
- "date": "2016-04-30T19:20:06+0200",
|
|
|
- "remoteAddr": "127.0.0.1",
|
|
|
- "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
|
|
|
- },
|
|
|
- {
|
|
|
- "referer": "google.com",
|
|
|
- "date": "2016-04-30T19:19:57+0200",
|
|
|
- "remoteAddr": "1.2.3.4",
|
|
|
- "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
|
|
|
- },
|
|
|
- {
|
|
|
- "referer": null,
|
|
|
- "date": "2016-04-30T19:17:35+0200",
|
|
|
- "remoteAddr": "127.0.0.1",
|
|
|
- "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
|
|
|
- }
|
|
|
- ],
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**ERROR RESPONSE**
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "error": "INVALID_ARGUMENT",
|
|
|
- "message": "Provided short code \"abc123\" is invalid"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Posible errors:
|
|
|
-
|
|
|
-* **INVALID_ARGUMENT**: The shortcode does not belong to any short URL
|
|
|
-* **UNKNOWN_ERROR**: Something unexpected happened.
|