Apisentris is a platform that turns your any database schemas into RESTful API.

Custom API servers suffer problems. Writing business logic often duplicates, ignores or hobbles database structure. Object-relational mapping is a leaky abstraction leading to slow imperative code. Apisentris philosophy establishes a single declarative source of truth: the data itself.

As the development of security measures, many APIs are content with just having an API key or username passed in as a parameter when an endpoint is called. The danger with that scheme is that the API token might be stolen for abuse.

Apisentris has authentication method which is combination of basic authentication and whitelisting client references to keep API authentication simplicity without sacrificing the security.

Basic Authentication

Each connection has its own client id and access token. Simply those identifier should be included as request header in every request.

Whitelist Client

This method will ensure whether clients has privilege to make a request to the APIs or not. Just keep in mind, if there is no whitelisted clients so it will be considered all incoming requests will be granted to receive the API responses.

Go to the connection details page then add whitelist. It is accepting both IP addresse and Domain Name Server. Nothing to do with your API request after that, Apisentris will take care everything.

All tables in the active schema are available for querying. They are exposed in one-level deep routes. For instance the full contents of a table articles is returned at:

Response:

        
[
  {
    "id":1,
    "title":"Some Title",
    "content": "Long text description."
  },
  {
    "id":2,
    "title":"Some Another Title",
    "content": "Long text description."
  }

]
        
      

Ordering

The reserved word order_by reorders the response rows.

It uses a comma-separated list of columns and directions.

Limit and Pagination

Apisentris provides a limit and offset clause that is used to specify the number of records to return. The limit and offset clause makes it easy to code multi page results or pagination response, and is very useful on large tables. Returning a large number of records can impact on performance.

Assume we wish to select all records from 1 - 30 (inclusive) from a table called articles. The request would then look like this.

Filtering

You can filter result rows by adding conditions on columns, each condition is a query string parameter. For instance, to return people aged under 13 years old:

Multiple parameters can be logically conjoined by:

These clauses are available:

Selecting

When certain columns are wide (such as those holding binary data), it is more efficient for the server to withhold them in a response. The client can specify which columns are required using the select parameter.

Response:

        
[
  {
    "firstname":"John",
    "lastname": "Doe"
    "email": "[email protected]"
  },
  {
    "firstname":"John",
    "lastname":"Lark",
    "email": "[email protected]"
  }

]
        
      

Association

In Apisentris, an association is a connection between two tables that make common operations simpler and easier.

Given a user (with id 1) has many books, so the endpoint will be:

Response:

      
[
  {
    "id":1,
    "title":"Book",
    "user_id": 1
  },
  {
    "id":2,
    "title":"Book 2",
    "user_id": 1
  },
]
      
    

In the example above, books's foreign key should be user_id. But you can specify foreign key in fk query string if it has custom column name.

Embedded Resources

In addition to providing RESTful routes for each table, Apisentris allows related resources to be included together in a single API call. This reduces the need for multiple API requests. The server uses foreign keys to determine which tables and views can be returned together. For example, consider a database of books with their authors and their user - has many authors (plural) and belongs to user (singular).

Response:

      
[
  {
    "id":1,
    "title":"Book",
    "user_id": 1,
    "user": {
      "name": "Tony Doe",
      "email": "[email protected]"
    },
    "authors": [
      {"name": "Deni"}
    ]
  },
  {
    "id":2,
    "title":"Book 2",
    "user_id": 2,
    "user": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "authors": [
      {"name": "Zoro"}, {name: "Dito"}
    ]
  },
]
      
    

You can filter embedded query result rows by adding conditions on columns, each condition is a query string parameter. Multiple query strings separated by comma.

Embedded Filtering

Prefix the query parameters with the name of the embedded resource.For instance, to select all users that having "Harry Potter" book:

We can combining the endpoint with other query string as well:

Response:

      
[
  {
    "id":1,
    "name":"John Doe",
    "books": [
      {"name": "Harry Potter and the Chamber of Secret"},
      {"name": "Lord of the Ring"}
    ]
  },
  {
    "id":11,
    "name":"John Cena",
    "books": [
      {"name": "Harry Potter and the Goblet of Fire"},
      {"name": "The Lean Startup"},
      {"name": "Rich Dad Poor Dad"}
    ]
  },
]
      
    

Custom Query

The Apisentris grammar limits the kinds of queries clients can perform. It prevents arbitrary, potentially poorly constructed and slow client queries. The most common causes for custom endpoints are:

• Table unions
• More complicated joins than those provided by Resource Embedding
• Geo-spatial queries that require an argument
• Sophisticated full-text search

Request Body:

      
{
  "query": "SELECT column_name(s) FROM table1 LEFT JOIN table2 ON table1.column_name = table2.column_name"
}
      
    

Request Body (for MongoDB):

      
{
  "query": {
    "collection": "demo_db", // collection name
    "operator": "text_search", // operator, see table below
    "command": { // query
      "$text": {
        "$search" : "ardian"
      }
    }
  }
}
      
    

These operators are available for MongoDB custom query:

Apisentris uses RESTful as its architectural style and communication approach. Primary key should be defined in the table as resource identifier.

It will return single JSON object for the convenience of your client side. e.g.

        
{
  "id": 1,
  "name":"My First Article",
  "content":"Long text content",
  "published":true
}
        
      

To create a row in a database table post a JSON object whose keys are the names of the columns you would like to create. Missing properties will be set to default values when applicable.

Request Body:

        
{
   "resource": {
        "title":"Some Title",
        "content": "Long text description."
   }
}
        
      

Response:

        
{
  "id":1,
  "title":"Some Title",
  "content": "Long text description."
}
        
      

To update a row in a table, use the PATCH verb and RESTful uri followed with table's primary key.

Request Body:

        
{
   "resource": {
        "title":"Updated Title",
        "content": "Updated content."
   }
}
        
      

Response:

        
{
  "id":1,
  "title":"Updated Title",
  "content": "Updated content."
}
        
      

To delete row in a table, use the DELETE verb and RESTful uri followed with table's primary key.

An external service can provide user management and coordinate with the Apisentris using JWT. It’s also possible to support login and user signup entirely through Apisentris.

Register

Request Body:

        
{
   "auth": {
        "email":"[email protected]",
        "password":"somepassword",
        "password_confirmation":"somepassword",
   }
}
        
      

Success Response:

        
{
  "id":1,
  "email":"[email protected]"
}
        
      

        
{
    "password_confirmation": [
        "doesn't match Password"
    ],
    "email": [
        "has already been taken"
    ]
}
        
      

        
{
   "auth": {
        "email":"[email protected]",
        "password":"somepassword"
   }
}
        
      

        

{
  "jwt": "jwt_token_with_payload"
}
        
      

        
{
   "auth": {
        "email":"[email protected]",
        "password":"update_somepassword",
        "password_confirmation":"update_somepassword",
   }
}
        
      

        
{
  "id":1,
  "email":"[email protected]"
}
        
      

        
{
    "password_confirmation": [
        "doesn't match Password"
    ],
    "email": [
        "has already been taken"
    ]
}