PHP Classes

Polr Restful API: Provide an API for the Polr URL shortener service

Recommend this page to a friend!
  Info   View files Documentation   View files View files (16)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 58 This week: 1All time: 10,492 This week: 560Up
Version License PHP version Categories
polr-api 2.0.0GNU General Publi...5HTTP, PHP 5, Web services
Description 

Author

This package provides an API for the Polr URL shortener service.

It provides several end points for the API URLs that give access to different features of the shortener.

Currently the the API gives access to all Polr users, links and stats features, except user creation and deletion, password change, and link redirection.

Picture of Thierry Feuzeu
  Performance   Level  
Name: Thierry Feuzeu <contact>
Classes: 13 packages by
Country: Cameroon Cameroon
Age: 47
All time rank: 21801 in Cameroon Cameroon
Week rank: 106 Up1 in Cameroon Cameroon Equal
Innovation award
Innovation award
Nominee: 1x

Documentation

Polr API

A Restful API for the Polr URL Shortener

Features

This package gives access to all Polr features through a Restful API, excepted the following.

  • User creation and deletion.
  • Password change.
  • Link redirection.

Installation

Add the Github repository and package to the composer.json file of your Polr installation, and run composer update.

{
    "repositories": [
        {
            "type": "git",
            "url": "https://github.com/lagdo/polr-api"
        }
    ],
    "require": {
        "lagdo/polr-api": "dev-master"
    }
}

Register the service provider in the bootstrap/app.php.

$app->register(\Lagdo\Polr\Api\PolrApiServiceProvider::class);

Documentation

The API endpoints are documented here. The documentation is generated with API Doc.

Known issues

Sometimes the requests to the API return with errors due to CSRF verification failure. That's because Polr has disabled CSRF verification only for its own API endpoints.

This API endpoints then need to be also added in the app/Http/Middleware\VerifyCsrfToken.php file.

    public function handle($request, \Closure $next) {
        if ($request->is('api/v/action/') ||
            $request->is('api/v/data/') ||
            $request->is('api/v/links/') ||
            $request->is('api/v/users/') ||
            $request->is('api/v/stats/')) {
            // Exclude public API from CSRF protection
            // but do not exclude private API endpoints
            return $next($request);
        }

        return parent::handle($request, $next);
    }

Details

<a name="top"></a>

Polr API v2.0.0

Restful API for the Polr URL Shortener

Links

Delete a link

Back to top

<p>Delete the link with the given ending.</p>

DELETE /links/:ending

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to delete links.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a link with the given ending.</p>|

Get Admin Links

Back to top

<p>Fetch a paginated list of links. The input parameters are those of the Datatables library.</p>

GET /links

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | draw | Integer | optional<p>The draw option.</p>| | columns | Object | optional<p>The table columns.</p>| | order | Object | optional<p>The data ordering.</p>| | start | Integer | optional<p>The data offset.</p>| | length | Integer | optional<p>The data count.</p>| | search | Object | optional<p>The search options.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Object | <p>The link list.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to list links.</p>|

Get User Links

Back to top

<p>Fetch a paginated list of links. The input parameters are those of the Datatables library.</p>

GET /users/me/links

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | draw | Integer | optional<p>The draw option.</p>| | columns | Object | optional<p>The table columns.</p>| | order | Object | optional<p>The data ordering.</p>| | start | Integer | optional<p>The data offset.</p>| | length | Integer | optional<p>The data count.</p>| | search | Object | optional<p>The search options.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Mixed | <p>The link list.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to list links.</p>|

Lookup Link

Back to top

<p>Returns</p>

GET /links/:ending

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | secret | String | optional<p>The link secret.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Object | <p>The link data.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a link with the given ending.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>Invalid URL code given for a secret URL.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Shorten a link

Back to top

<p>Create a shortened URL for a given link</p>

POST /links

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | url | String | <p>The link to shorten.</p>| | ending | String | optional<p>A custom ending for the link.</p>| | secret | String | optional<p>Create a secret link or not.</p>| | ip | String | optional<p>The IP address the request came from.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Mixed | <p>The shortened URL.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | CreationError | Object | <p>An error occurs while shortening the link.</p>| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Update a link

Back to top

<p>Update the link with the given ending.</p>

PUT /links/:ending

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | url | String | optional<p>The new URL.</p>| | status | String | optional<p>The status change: enable, disable or toggle.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to edit the link.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a link with the given ending.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Stats

Get Link Stats

Back to top

<p>Fetch stats of a given type for a single link.</p>

GET /links/:ending/stats

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | type | String | <p>The type of stats to fetch.</p>| | ending | String | <p>The short URL id of the link.</p>| | left_bound | String | <p>The start date.</p>| | right_bound | String | <p>The end date.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Mixed | <p>The stats data.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to view stats.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AnalyticsError | Object | <p>An error occurs while fetching stats from the database.</p>| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Get Stats

Back to top

<p>Fetch stats of a given type.</p>

GET /stats

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | type | String | <p>The type of stats to fetch.</p>| | left_bound | String | <p>The start date.</p>| | right_bound | String | <p>The end date.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Mixed | <p>The stats data.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to view stats.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AnalyticsError | Object | <p>An error occurs while fetching stats from the database.</p>| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Users

Change API Settings

Back to top

<p>Change the API Settings of the user with the given id.</p>

PUT /users/:id/api

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | quota | String | optional<p>The new API quota.</p>| | status | String | optional<p>The API access change: enable, disable or toggle.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Object | <p>The updated user data.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to edit the user.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a user with the given id.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Generate Key

Back to top

<p>Generate a new API access key for the user with the given id.</p>

POST /users/:id/api

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Mixed | <p>The updated user data.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to edit the user.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a user with the given id.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Get a User

Back to top

<p>Get the user with the given id</p>

GET /users/:id

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Object | <p>The user data.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to get users.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a user with the given id.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|

Get Users

Back to top

<p>Fetch a paginated list of users. The input parameters are those of the Datatables library.</p>

GET /users

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | draw | Integer | optional<p>The draw option.</p>| | columns | Object | optional<p>The table columns.</p>| | order | Object | optional<p>The data ordering.</p>| | start | Integer | optional<p>The data offset.</p>| | length | Integer | optional<p>The data count.</p>| | search | Object | optional<p>The search options.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Object | <p>The user list.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to list users.</p>|

Update a user

Back to top

<p>Update the user with the given id.</p>

PUT /users/:id

Parameter Parameters

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | key | String | <p>The user API key.</p>| | role | String | optional<p>The new role.</p>| | status | String | optional<p>The user status change: enable, disable or toggle.</p>|

Success 200

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | message | String | <p>The response message.</p>| | settings | Object | <p>The Polr instance config options.</p>| | result | Object | <p>The updated user data.</p>|

Error 401

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | AccessDenied | Object | <p>The user does not have permission to edit the user.</p>|

Error 404

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | NotFound | Object | <p>Unable to find a user with the given id.</p>|

Error 400

| Name | Type | Description | |:---------|:-----------|:--------------------------------------| | MissingParameters | Object | <p>There is a missing or invalid parameter.</p>|


  Files folder image Files  
File Role Description
Files folder imagedocs (1 file)
Files folder imagesrc (1 file, 2 directories)
Files folder imagetests (2 files)
Accessible without login Plain text file apidoc.json Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  docs  
File Role Description
  Accessible without login Plain text file api.md Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
Files folder imageHelpers (3 files)
Files folder imageHttp (1 file, 2 directories)
  Accessible without login Plain text file PolrApiServiceProvider.php Class Class source

  Files folder image Files  /  src  /  Helpers  
File Role Description
  Accessible without login Plain text file ResponseHelper.php Class Class source
  Accessible without login Plain text file StatsHelper.php Class Class source
  Accessible without login Plain text file UserHelper.php Class Class source

  Files folder image Files  /  src  /  Http  
File Role Description
Files folder imageControllers (3 files)
Files folder imageMiddleware (1 file)
  Accessible without login Plain text file routes.php Example Example script

  Files folder image Files  /  src  /  Http  /  Controllers  
File Role Description
  Accessible without login Plain text file LinkController.php Class Class source
  Accessible without login Plain text file StatsController.php Class Class source
  Accessible without login Plain text file UserController.php Class Class source

  Files folder image Files  /  src  /  Http  /  Middleware  
File Role Description
  Accessible without login Plain text file RestApiMiddleware.php Class Class source

  Files folder image Files  /  tests  
File Role Description
  Accessible without login Plain text file ExampleTest.php Class Class source
  Accessible without login Plain text file TestCase.php Class Class source

 Version Control Reuses Unique User Downloads Download Rankings  
 100%1
Total:58
This week:1
All time:10,492
This week:560Up