• Currently version is Spring v2.0.
• Documentation Fall v1.0.8.

Documentation v2.0

1. Authentication
2. Route parameters
3. Query syntax
4. Query operators
5. Collection rules
6. Methods
7. Examples:
   • GET:
     • Get all records
     • Get record by id ($primaryKey)
     • Get record by column
     • Get filtered records
     • Get limited records
     • Get records with limit and offset
     • Get records with pagination
     • Get records with collection rules
     • GET Response body
   • POST:
     • Create a record
   • PUT:
     • Update record by id ($primaryKey)
     • Update record by column
     • Update many records by query filter
   • DELETE:
     • Delete record by id ($primaryKey)
     • Delete record by column
     • Delete many records by query filter

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.

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.

4. Query operators:

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.

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.

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 */

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.