Baasic REST API documentation will probably be the starting point for your exploration of Baasic functionality. Baasic back-end contains various built-in modules that can be easily consumed through its REST endpoints. Let’s find out more about the modules that can be used this way.

  • Core - Application management, statistics, notifications, and related modules;
  • Membership Module - User management system, including support for user registration, social log-in, password recovery, fully-featured role management and many more;
  • Key Value Module - The simplest, yet most flexible storage mechanism that will store almost any kind of key-value data sets;
  • Value Set Module - A storage mechanism that will store any kind of list data sets;
  • Article Module - Fully featured article module with support for drafts, publishing workflows, archives, tagging, comments, ratings and media resources. Alpha version, not all features are available;
  • Dynamic Resources - A storage mechanism for your custom data objects, enabling you to make them first-class citizens in your apps. You can utilize features like advanced querying, filtering, sorting and fine-grained validation.

    Supported features

    Interaction with the Baasic API is pretty much straightforward; like most other APIs we are using simple HTTP formats which provide a consistent and simple way to link between API resources. Let me explain some of its features in more detail.

HTTP formats

  • JSON (application/json)
  • HAL JSON (application/hal+json)

It’s important to know that Baasic supports and recommends HAL+JSON format as a default. Baasic SDKs will have HAL+JSON set as default HTTP format for communication with the back-end. For more details on the HAL+JSON conventions, please visit one of the following resources JSON Schema Hypermedia or HAL Specification.

HAL

Here is an example of a resource returned from Baasic in HAL format:

{
    "key": "my-key",
    "value": "my-value",
    "dateCreated": "2015-01-01T14:24:56.795849Z",
    "dateUpdated": "2015-01-01T14:24:56.795849Z",
    "id": "kZyiWLUzz8dqAjHiO1gxXK",
    "_links": {
        "self": {
            "href": "https://api.baasic.com/beta/app-id/key-values/my-key",
            "templated": false
        },
        "post": {
            "href": "http://api.baasic.com/beta/app-id/key-values",
            "templated": false
        },
        "put": {
            "href": "http://api.baasic.com/beta/app-id/key-values/my-key",
            "templated": false
        },
        "delete": {
            "href": "http://api.baasic.com/beta/app-id/key-values/my-key",
            "templated": false
        }
    },
    "_embedded": { }
}

To manually access the predefined links, one should use the _links property from the returned resource:

_links.put.href
_links.delete.href

Embeds

To reduce the number of round-trips to the back-end, embeds can be used. Available embeds can be found in the _embedded property if HAL+JSON format is used, or in the object itself if you choose plain JSON. Here is how they look:

HAL+JSON

"_embedded": {
    "author": { },
    "comments": [ ],
    "ratings": [ ],
    "tags": [ ]
}

JSON

{
    "author": { },
    "comments": [ ],
    "ratings": [ ],
    "tags": [ ]
}

Note: Embeds are returned as empty objects or arrays if not explicitly requested through the embed query parameter.

Fields

To define which fields should be returned from the REST API, fields query parameter should be used. You can comma-separate field names and use the dot notation for embedded resources.

Search Types

Every Baasic REST endpoint that returns a collection can be filtered using one of the following techniques:

  1. BQL or Baasic Query Language can be used by adding the searchQuery query parameter in order to filter the available resources. BQL uses a subset of the standard SQL syntax - most often a simple WHERE clause - here is sample of a typical GET method that uses this technique:

     http://api.baasic.local/beta/baasic/article/?searchQuery=WHERE%20Field%20%3D%20%27Value%27&embed=Author,Tags,Comments,Ratings&page=
    

    Note: This type of search is case-sensitive.

  2. In contrast to the BQL search, Phrase Search should contain values of resource properties. Only resources containing properties that match the search keyword will be listed. Here is an example of the phrase search on the article endpoint, along with the embed, paging and custom status parameters:

    http://api.baasic.local/beta/baasic/article/?searchQuery=myqueryterm&embed=Author,Tags,Comments,Ratings&page=1&statuses=published,draft,archive
    

    Notes:

    • This type of search is case-insensitive;
    • Some resource properties may not be searchable.

HTTP Operations

Baasic allows operating on available resource representations, wherein each one is identified by URL and can be used via HTTP CRUD operations: - GET - retrieves the specified resource, - DELETE - permanently removes the specified resource, - POST - creates a new instance of a resource and - PUT - updates the specified resource.

Besides these standard HTTP operations, Baasic supports PATCH for partial updates.


Our primary goal with the REST API documentation is to utilize your time effectively so we provide as many information as possible for implementing your Baasic solutions. The following information will be available for all Baasic REST API end-points: - Description - documents the purpose of an end-point; - Returns - documents the return value of an end-point; - Parameters - documents all end-point arguments exposing their usage, type and requirements (required or optional); - Response Codes - documents information about the status of the end-point request; - Code Examples - CURL and sometimes JSON code samples; - Available Object Definitions - documents structure of objects contained within end-point’s response and - Notes - documents additional data necessary for better understanding of an end-point.

We’ll be providing regular updates to our REST API documentation to provide support for the new Baasic API changes over the coming months. Please feel free to send us your feedback and thoughts via Baasic Support or Twitter.

Thank you for supporting Baasic. We are looking forward to see what you can build with a bit of help from our platform!

Feel free to leave a comment

comments powered by Disqus