64
$299.99
Add to project

Product support

Visit this product's website for support.

Categories

Introduction

Simple API, allows exposing any model using API Rest. It is safe and easy to configure. You can create multiple credentials and custom permissions for as many applications as you need. Connect and manage your October Project from another Project, App or CRM.

Method & Functions

All of the basic functionality that you are familiar with OctoberCMS control panel is available through the API.

Method Function
GET Get all records
GET Get record by id ($primaryKey)
GET Get record by column
GET Get filtered records
GET Get limited records
GET Get records with limit and offset
GET Get records with pagination
GET Get records with relations
GET Get records with collection rules
POST Create a record
PUT Update record by id ($primaryKey)
PUT Update record by column
PUT Update many records by query filter
DELETE Delete record by id ($primaryKey)
DELETE Delete record by column
DELETE Delete many records by query filter

Currently version is Spring v2.0.

Documentation v2.0

  1. Authentication
  2. Route parameters
  3. Query syntax
  4. Query operators
  5. Collection rules
  6. Methods
  7. Examples:

1. Authentication:

Simple API, require "Basic Auth". You must create the credentials and provide Client ID and API Key on all requests.

Go to Settings > Simple API > Tokens.

2. API Route parameters:

The magic of the API endpoint, allows to work with the most recent and previous versions. And use data collection rules, with a friendly syntax.

Parameter Required Description
:version * The api version in use.
:resource * Name of the resource.
:query ? To filter records with query syntax.
:rules ? To add collection rules.

API Route:

GET: ~/api/:version/:resource/:query?/:rules?

3. Query syntax:

Replace :query of the route. Multiple filters may be delimited using either a "pipe" character.

Replace Parameter description e.g
:query value To get a record by ID ($primaryKey), replace :query only with the id value. 4e5b6486
:query column:value To add a simple filter by $column and $value published:true
:query column:operator:value To add comparative filter by $column, $operator, and $value. id:not:null

4. Query operators:

Operator description
is Equal to
not Not equal to
lt Less than
gt Greater than
lte Less than or equal
gte Greater than or equal
contains Contains
!contains Not contains

Example:

GET: ~/api/v2/posts/published:true|published_at:gte:2019-01-01 00:00:00|excerpt:not:null

5. Collection rules:

Below is a list of all available collection rules and their function. Multiple rules may be delimited using either a "pipe" character.

Replace Parameter description e.g
:rules first Get only the first record. first
:rules limit:max To limit the max of results returned from the query. limit:100
:rules offset:skip,take To skip a given number of results in the query, you may use the skip and take. offset:1,10
:rules order:column,direction The first argument to the order should be the column you wish to sort by, while the second argument controls the direction of the sort and may be either asc or desc. order:published_at,desc
:rules paginate:items,page Indicate in the first argument the number of items per page, and in the second the current page. paginate:15,2
:rules select:col1,col2,col3 Using the select parameter, you can specify a custom select clause for the query. select: id,title,excerpt
:rules with:rel1,rel2 When querying, you may specify which relationships should be eager loaded using the with parameter. with:categories,featured_images

Example:

GET: ~/api/v2/posts/published:true/select:id,title,excerpt|with:categories,featured_images|order:published_at,desc|limit:100

6. Methods:

Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Method Usage
GET For simple retrieval of data. Any request using the GET method is read-only and will not affect any of the objects you are querying.
POST To create a new record. If any column or field fails, the new record will not be created.
PUT The PUT method can be used to update records that already exist in the database.
DELETE To delete records.

7. Examples:

Below is a list of sample applications, which apply to RainLab.Blog (posts).

GET (read):

Get all records:

GET: ~/api/v2/posts

Get record by id ($primaryKey):

GET: ~/api/v2/posts/3

Get record by column:

GET: ~/api/v2/posts/slug:hello-world/first

Get filtered records:

GET: ~/api/v2/posts/published:true|published_at:gte:2019-01-01 00:00:00

Get limited records:

GET: ~/api/v2/posts/published:true/limit:100

Get records with limit and offset:

GET: ~/api/v2/posts/published:true/offset:15,15

Get records with pagination:

GET: ~/api/v2/posts/published:true/paginate:15,2

Get records with collection rules:

GET: ~/api/v2/posts/published:true/select:id,title,slug|with:categories,featured_images|order:published_at,desc|limit:15

Get response body:
{
    "status": "success",
    "data": {
        "id": 3,
        "title": "Prueba de actualización por filter",
        "slug": "post-de-prueba",
        "published": 1,
        "categories": [],
        "featured_images": []
    }
}

POST (create):

Create a record:

POST: ~/api/v2/posts
-H "Content-Type: application/json"
{
    "title": "Hello world",
    "slug": "hello-world",
    "content": "<p>Post content...</p>"
}
Response body:
{
    "status": "success",
    "data": {
        "id": "12",
        "title": "Hello world",
        "slug": "hello-world",

        & more...
    }
}

PUT (update):

Update record by id ($primaryKey):

PUT: ~/api/v2/posts/3
-H "Content-Type: application/json"
{
    "title": "Hello world",
    "slug": "hello-world",
    "content": "<p>Update content...</p>"
}
Response body:
{
    "status": "success",
    "data": {
        "id": "3",
        "title": "Hello world",
        "slug": "hello-world",
        "content": "<p>Update content...</p>",

        & more...
    }
}

Update record by column:

PUT: ~/api/v2/posts/slug:hello-world/first
-H "Content-Type: application/json"
{
    "title": "Hello world",
    "slug": "hello-world",
    "content": "<p>Update record by column...</p>"
}
Response body:
{
    "status": "success",
    "data": {
        "id": "3",
        "title": "Hello world",
        "slug": "hello-world",
        "content": "<p>Update record by column...</p>",

        & more...
    }
}

Update many records by query filter:

PUT: ~/api/v2/posts/published:not:true
-H "Content-Type: application/json"
{
    "published": 1
}
Response body:
{
    "status": "success",
    "data": {
        "rows": 3
    }
}

/* Returns the number of affected rows */

DELETE (delete):

Delete record by id ($primaryKey):

DELETE: ~/api/v2/posts/3

Delete record by column:

DELETE: ~/api/v2/posts/slug:hello-world/first

Delete many records by query filter:

DELETE: ~/api/v2/posts/published:false
Response body:
{
    "status": "success",
    "data": {
        "rows": 1
    }
}

/* All deletion requests return the number of affected rows */

  • Found the plugin useful on 28 Jan, 2019

    how can i make an aggeration function like count

  • author

    Replied on 28 Jan, 2019

    Hello,

    You have several options:

    1. We can give you access to the repository and do it yourself.
    2. you can make a query to the api and make a count in your endpoint.
    3. We can do it for you, in the plugin but we do not have much time, I can next week.

    You can send us a message from the author page. https://octobercms.com/author/awebsome

  • Found the plugin useful on 13 Dec, 2018

    Hello,

    No clue how to ask you for support for this plugin. No examples or how to use. Can you help please?

    Thank you, Gavin

  • author

    Replied on 10 Jan, 2019

    Hello, you can send us a message from the author page. https://octobercms.com/author/awebsome

  • Found the plugin useful on 2 May, 2018

    Works great. Docs need a little work (a walk through or examplE) but this is a new plugin. Developer was very responsive with my questions and got everything working.

2.0.0

!!! Add Api v2.0

Jun 26, 2019

1.0.8

Minor changes

Oct 28, 2018

1.0.7

Minor Fix in POST method

Jun 20, 2018

1.0.6

Minor Fix Update with POST/PUT

Jun 20, 2018

1.0.5

Minor fix (resolve table name of resource)

May 09, 2018

1.0.4

Update Tokens Permissions

Mar 31, 2018

1.0.3

Update Resources Table

Mar 31, 2018

1.0.2

Create Tables

Mar 31, 2018

1.0.1

Initialize plugin.

Mar 31, 2018

Upgrading to 1.0.8 from 2.0

This update has successfully passed the tests we have done, but seriously consider updating this plugin in a test or development environment.

Required actions:

  1. Delete the template api.htm file.

    This page is deprecated, you can delete it.

  2. Check all your resources that are correctly configured.

    The update script does this task for you, but be careful and check it yourself.

  3. All ready.

    Ready to work with the api v2.0. Check the documentation.