Questions? Feedback? powered by Olark live chat software
API - AaaS

API



AaaS API is very simple and easy to integrate. No client libraries or download is needed to use the API. API has set of web services to add, search and manage the data records

This API documentation describes how data is structured in Records and set of API requests to manage data.

HTTPS only

All API requests must be made over HTTPS.


Authentication

AaaS API authenticates the requests using HTTP basic auth. The username is your application id and the password is your API key. Your application id and API key can be obtained from the Dashboard.

By default authentication is not enabled for search method. However, authentication can be enabled for search method from dashboard.


Records

Data is added in form of Records. Each record has a title.

Record can have metadata about the record. Metadata can be used to add useful information about the record. e.g. description, image url, links.

The search method returns records whose title matches the search query. The metadata is not matched against the search query.

Records can also have tags. Tags are helpful if you want to apply filters to searches


Each Record Object has following attributes

Attribute Name Description
title Title of the record
utils The metadata about the Record
tags Each record can have tags. Multiple tags are specified by separating them with a semicolon. This field is optional
id unique identifier of the record. This field is generted by AaaS


Example Record object in JSON
{  
  "title": "Integrating autocomplete search into my mobile app",
  "utils": "www.example.com/integrating-autocomplete-into-my-mobile-app",
  "tags": "author=mark;category=engineering;23-04-2014",
  "id": "15961645281674959089"
}            


Sections

Records can be divided into sections. In the search requests you can specify which section you want to get the results from.

Sections let you separate records and create filtered searches for your data.

For example - You are a news website and want to divide news articles for differet locations. You can create one section for each location. In your search requests, you can specify the section you want the news articles from.

Having sections for your records is optional. You can simply add records without any section.

Sections can be created using add section web service.


Structure

Following diagram describes how data in strcutured into sections. Records not added into any section will be matched when no section is specified in search requests.


Error Handling

API response uses the standard HTTP status codes to indicate success or error in API calls. Following is list HTTP codes that API calls return

Code Description
400 Missing or bad input parameter. Error message contains details
401 Authorization Failed
404 Record not found
507 API usage quota is over or the maximum records limit reached. Error message contains details
500 Server Error
429 You are sending too many request. The API requests are rate-limited per customer account
Response

In case of non 200 HTTP response, the response contains JSON-formatted message indicating the reason. Below is an example:

{"message":"Required parameter title not provided"}


Add Record

Records are added using the add record requests.

URL
POST https://api.aaas.io/v1/add/{section_name}

The section_name is optional, it specifies which section the record must be added to.

If section_name is not provided then record will not be added into any specific section. Such records will be matched when no section is specified in search requests.

The section must be created using add section request before adding Record.


Parameters
title

Required. Title of the Record. Maximum length of title is 256 characters

utils

Optional. The metadata about the Record. Maximum length of utils is 2000 characters

tags

Optional. Maximum length of tags field is 512 characters. Multiple tags can be specifed by separating them with a semicolon. You can add upto 5 tags

application_id

Required. Your application id, obtained from dashboard


Example Request Code
$ curl https://api.aaas.io/v1/add  \
-d application_id={your_application_id} \
-d "title=Integrating autocomplete search into my mobile app" \
-d "utils=www.example.com/integrating-autocomplete-into-my-mobile-app" \
-u {your_application_id}:{your_app_key} \

curl uses the -u flag to pass basic auth credentials
Response

The response contains the unique auto-generated id of the record.

Example Response
{"id":"15961645281190807878"}


Search Records

Records are searched using the search record method. This method returns records whose title match the search query.

Note: Your API call count is incremented only when you call the search method. Calling any other method of the API does not increment API call count.

Authentication is optional for this method and is not enabled by default. However, authentication for this method can be enabled from dashboard. Authentication method is same as described in Authentication section above

URL
GET https://api.aaas.io/v1/search/{section_name}

The section_name is optional. If passed, then the records added into the specified section will be searched.


Parameters
term

Required. Search query. The text to be searched

application_id

Required. Your application id, obtained from dashboard

tags

Optional. Records having the specified tags will only be searched. If multiple tags are provided, then records having all the specified tags will be searched.

get_id

Optional. If this parameter is set to "true", then the ids of the record will also be returned in the response


Example Request Code
$ curl https://api.aaas.io/v1/search?application_id={your_application_id}&term="query"
Response

The response contains the records matched against the search query. Response is encoded as JSON array containing array of records.

Example Response
[
    {
        "title": "Integrating autocomplete search into my mobile app",
        "utils": {
            "link": "www.example.com/p108",
            "image": "gl.com/image.png",
            "author": "Michael"
        }
    },
    {
        "title": "mobile apps are more user friendly with autocomplete search",
        "utils": {
            "link": "www.example.com/p118",
            "image": "fb.com/image.png",
            "author": "Mark"
        }
    },
    {
        "title": "Most users expect autocomplete searches in apps ",
        "utils": {
            "link": "www.example.com/p136",
            "image": "gl.com/image.png"
        }
    }
]



Delete Record

Records are deleted using the delete record method. The id of the record to be delete is passed as parameter. It deletes the record whose id matches the given id.

If the id of the record is not known then title can also be passed as parameter. It will delete the record whose title matches the given title. If there are multiple records matching the given title, then all such records will be deleted.

If both id and title the record are passed, then it will consider id to delete the record. At lease one of these two parameters must be passed to delete the record successfully.

URL
POST https://api.aaas.io/v1/delete/{section_name}

If the record was added into a section then section_name must be added in the above URL

Parameters
title

Optional. Title of the record to be deleted

id

Optional. id of the record to be deleted

application_id

Required. Your application id, obtained from dashboard


Example Request Code
$ curl https://api.aaas.io/v1/delete \
-d application_id={your_application_id} \
-d "title=Integrating autocomplete search into my mobile app" \
-u {your_application_id}:{your_app_key} 

curl uses the -u flag to pass basic auth credentials
Response

The response contains the result of the method call.

Example Response
{"message":"Record Deleted Successfully"}
Error
404 - If record with given title or id not found


Add Section

Sections are added using the add section method.

URL
POST https://api.aaas.io/v1/add_section

Parameters
section_name

Required. Name of the section to be created. Maximum length is 20

application_id

Required. Your application id, obtained from dashboard


Example Request Code
$ curl https://api.aaas.io/v1/add_section \
-d application_id={your_application_id} \
-d section_name="books" \
-u {your_application_id}:{your_app_key}  

curl uses the -u flag to pass basic auth credentials
Response

The response contains the result of the method call.

Example Response
{"message":"Section added successfully"}
Error
400 - Section already exists


Delete Section

Sections are deleted using the delete section method.

When a section is deleted, all the records in that section are also deleted


URL
POST https://api.aaas.io/v1/delete_section

Parameters
section_name

Required. Name of the section to be delete.

application_id

Required. Your application id, obtained from dashboard


Example Request Code
$ curl -v https://api.aaas.io/v1/delete_section \
-d application_id={your_application_id} \
-d section_name="books" \
-u {your_application_id}:{your_app_key}

curl uses the -u flag to pass basic auth credentials
Response

The response contains the result of the method call, number of records deleted.

Example Response
{
"message":"Section deleted successfully",
"totalRecordsDeleted":"2"
}
Error
404 - Section not found