This service is in soft release. The back end is production ready, but the administration portal is a temporary one with just basic features as of now.
This documentation is intended for developers and administrators of AppSearch deployments.
To get started using AppSearch is quick and easy. A private index deployment will be deployed within a minute or two and as soon as deployed you can start using it in the API Services area of this portal and/or by accessing it from your own code.
The deployments area in the AppSearch admin portal gives you access to create and manage your deployments.
To create your own private search index, go to the Deployments section of the AppSearch portal. If you are a verified user, you will be able to create a new private deployment by clicking the "Create New Deployment" button.
When you've done so a private search index will be provisioned for you. This takes a few seconds before it is ready for use. When it is listed as status "Running" you can start using your search index.
If you are not yet a verified user, you will have a notification saying so and asking you to contact our support to get verified.
If you have more than one deployment you got a list of them on the top of the deployments page. Click on the deployment you want to manage in order to use the remove, rename, reset and restart functions.
If you want to delete your deployment you can use the remove deployment function. This will remove both data and the deployment itself.
If you want to give your deployment a custom name you can use the rename deployment option. This can be useful if you have multiple deployments and want to keep track of them easier.
The reset option will clear all the data in your deployment so you can start from scratch.
This option restarts your deployment node(s). This takes usually takes a few seconds. The time it takes to restart your deployment depends on the amount of data in your index.
The API can be used and tested in the portal UIs API Services section or remotely from your own code, postman etc. Read below how to use the API with API keys in various scenarios.
In the API Keys section of the AppSearch portal you will have your available API keys listed. This list includes two keys for your deployment, one read only and one read and write, and one test key for the demo node.
The read only key is intended for use wherever you want just access to the search and categorize functions but not to add and delete. Typically this is the key for end users that shouldn't be allowed to modify your search index.
The read and write key is intended for use wherever you want to add or remove items from your search index.
The demo key is used when you want to test the API in the AppSearch Portal UI (see more below).
If you want to test the API without creating a deployment you can do so with our demo deployment. If you look in your API Keys section of the portal, you will have a demo api key. This key can be used to play with the demo deployment.
To do so go to the API Services section in the AppSearch Portal. Click on the Authorize button in the top right-hand side and enter the demo api key. After you've done that, you can use the various API functions available on that page.
Please note that the demo deployment data is reset at rather short time intervals, so it is not intended for any extended test use.
To test your own index, you can also use the same portal admin interface or you can use the API url directly.
When you want to use the API remotely from your own code or tools like Postman you can access it at the following url:
https://appsearch.ayfie.com/api
To access it you need to use your API key that was listed in the API keys section of the portal. This API key should be passed on as a HTTP header parameter with the name "X-API-KEY".
This API uses two header fields. One is required and contains the API key while the other is optional and used for custom permissions when accessing items or categories.
This header is used for the API key. Without the correct API key for the deployment you want to access there you won't be able to perform any functions at all.
You can send multiple permissions in this header. The values are separated by a comma.
This header value is used to pass on end user permissions on search or list functions for categories and items. If this is empty the user will only be returned public items. This header is optional and not needed if you have only public items and no custom permissions.
The current functions supported by the API are adding/updating items, deleting items, searching and categorize.
The add items function adds new items to your index or updates existing ones if you already got an item added with the same id.
The add function is of type POST and you can add one or a batch of items using this function.
https://appsearch.ayfie.com/v1/items
The body content of the API function is a json structure containing the data of the item(s) you want to add.
Example:
[
{
"__id": "item-1",
"__permissions": ["myCustomPermission1"],
"__nonSearchableFields": ["author"],
"__categories": ["topic"],
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"description": "Programming is about polishing the craft with years of trial and error. Programming handbook.",
"author": "Robert C. Martin",
"topic": ["programming", "software", "clean code"]
},
{
"__id": "item-2",
"__permissions": ["myCustomPermission2"],
"__nonSearchableFields": ["author"],
"__categories": ["topic"],
"title": "Introduction to Algorithms",
"description": "The name of the book is self-explanatory. Programming handbook.",
"author": "Thomas H. Cormen",
"topic": ["programming", "software", "algorithms"]
}
]
This example json will insert 2 items into the index with the fields "title", "description", "author" and "topic" where the topic field will be used to define categories.
The __categories field indicates which field(s) you want to be made into categories for the item. The categories can later be used to filter on in searches. You can add an array of fields you want to use as categories.
If you want to use your own item id instead of an autogenerated one, you can use this field to specify the item id.
If you want to use custom permissions for your item, you can provide those with this field. This field is array based so you can provide multiple permissions you want applied to the item. If used only these permissions will be added to your item, not default ones.
If you do not provide any custom permissions a default permission will be added to the item. This same default permission will be added to any query without permissions specified. In essence the default permissions acts as a everyone/public permission.
This field can be used to specify fields in your item that should be content that is not searchable but that will be returned with the content data when searching.
Fields can be named anything and can be added as a simple string type field in the json structure as in with the "title" example above.
Fields that are used to define categories can have an array of values unlike regular data fields.
The delete item function will remove an item for your index.
To use it send a http delete request to the following url:
https://appsearch.ayfie.com/v1/Items/{id}
The id of the item to delete
An example URL of this call is:
https://appsearch.ayfie.com/api/v1/items/2c040e6c-170b-4c94-8ce1-58df0c7660b8
This GET function will by default list all the items you've got access to. You can however filter the items on the same parameters as with the search function but as query parameters. This function is best used for simple queries, for more complex one we recommend using the search function below.
If you use custom permissions you have to provide the permissions of the user querying in the X-API-Permissions HTTP header.
https://appsearch.ayfie.com/api/v1/items
All the parameters below are optional.
This param you use to filter by categories.
Here you provide the boolean query you want to query/filter by.
This parameter is used to do special operations/retrieve additional information typically useful for developers or debugging.
Possible values:
How many items should be skip at the beginning of the list of items that matches.
How many items you want returned from the point skip ends.
Which language we query in.
This is the main search function where you can search by using freetext and various filtering options.
https://appsearch.ayfie.com/api/v1/items/search
The function is called using a http POST request with a json structure containing your search data as the body content.
Example:
{
"query": "*",
"codeWords": null,
"response": {
"data": [
"Id",
"Content"
]
},
"filter": [
null
],
"skip": 0,
"take": 10,
"queryLanguage": "None",
"permissions": ["myCustomPermission1", "myCustomPermission2"]
}
This is the query expression you want to search for. If you search for * it will match all tokens, which results in returning every item you've got access to within your current search filter/specification.
This parameter is used to do special operations/retrieve additional information typically useful for developers or debugging.
Possible values:
With the response option you can select which data you want returned for your item hits. By default, all data is returned, but if you for instance only want the item id you can do so by adding a response filter like this:
"response": {
"data": [
"Id"
]
It is highly recommended that you don't as for/return more data than you need.
If you want search results within only a selected category/categories, you can do so using the filter option.
To filter your search to match only authors named "Thomas H. Cormen" you can do like this:
"filter": [
{ "author": "Thomas H. Cormen" }
]
You can also filter on multiple categories like author and country like this
"filter": [
{ "author": "Thomas H. Cormen", "country": "USA" }
]
When adding more fields in a filter your items will have to match all field values.
More than one filter can also be used in a single query:
"filter": [
{ "author": "Thomas H. Cormen", "country": "USA" },
{ "author": "Robert C. Martin", "country": "USA" }
]
When using multiple filters you will get hits on items that have either of the filters.
How many items to skip from the top of the ranked result list. If you want to start from the 15th ranked item, you set skip to 14.
The default value is 0.
How many search result items you want returned.
The default value is 10.
You can specify the language you are searching in. This will lead to stemming being applied to the search query in the language indicated to get a better search result.
The default option is None which will lead to no stemming being applied to the query.
Here you can provide an array of permission tokens/values that the search should be filtered by. Only items that match the permissions will be returned.
If you provide no permissions a default permission will be used which matches any items that have been added without custom permissions.
The list categories function executes a search and returns the full category structure or the categories with hits in based on your search query. The structure will contain an item hit count on each node.
The function url is:
https://appsearch.ayfie.com/api/v1/categories
The body content will contain your search specification.
This option can be used to decide if you want to return only categories that has matching items or all categories in your index. The default operation is DocumentHitsOnly.
The search categories function executes a search and returns the full category structure or the categories with hits in based on your search query. The structure will contain an item hit count on each node.
The function url is:
https://appsearch.ayfie.com/api/v1/categories/search
The function is called using a http POST request with a json structure containing your search data as the body content.
The body content will contain your search specification.
This is the query expression you want to search for. If you search for * it will match all tokens, which results in returning every item you've got access to within your current search filter/specification. The default value is '*'.
You can specify the language you are searching in. This will lead to stemming being applied to the search query in the language indicated to get a better search result.
The default option is None which will lead to no stemming being applied to the query.
This option can be used to decide if you want to return only categories that has matching items or all categories in your index. The default operation is DocumentHitsOnly.
The value QueryLanguage parameter values are: