Switch DB - Documentations

Switch API is the primary endpoint of data sevices and Switch DB's platform. You can do adding, editing, deleting or listing data works to your database with query operations by using this low-level API based on HTTP.

To call API, you need the login and create a database through the the developer portal with your private API Key and API Secret.

The URL format that is used for calling API:

GET /

https://{{API_LOCATION}}.switchapi.com/

All our servers are located as having n+1 backups in the data centers by using international standarts. Our Istanbul servers work at Radore, Izmir servers work at Netdirekt, Frankfurt servers are work at Amazon Web Services and IBM Cloud SoftLayer and also California servers work at Microsoft Azure.

You need Access Token parameter to make any request from API. For generating Access Token parameter, you can use /Token endpoint.

GET /Token

For generating Access Token, you need API Key and API Secret parameters that are provided from the developer portal. At the request, API Key that will be sent by using header is generated as portal API Key and Signature parameter is generated as md5(APISecret+ExpireTimestamp) format. At Expire parameter, token's expire date and time information must be proper to ISO 8601 standarts and Unix Time format with msec information.

Headers:

APIKey: {{API_KEY}}
Signature: {{SIGNATURE}}
Expire: {{EXPIRE}}

API Error Messages

API has a standart error message format. The standart error message answers as the format below.

{
	"ResponseTime": "2016-09-15T04:00:24.4749654+03:00",
	"Response": "ServiceException",
	"ErrorMessage": "Value cannot be null. Parameter name: 'AccessToken'."
}

For these errors, the response titles are like the below:

HTTP 401 - Unauthorized: Given AccessToken parameter is invalid.
HTTP 403 - SecurityException: Unsecured request.
HTTP 404 - MethodNotFound: Called API could not found.
HTTP 429 - TooManyRequests: API limit excess. The remaning time to the date-time for that API can answer the requests is calculated as Unix Time format under TheNextReset.
HTTP 500 - ServiceException: Unexpected Error There is a detailed explanation under ErrorMessage.

Switch API has 6 basic references for Switch DB works.

POST /Add

POST /Add is used for adding a data object to the list created at Switch DB. You can choose the list that will be added tha data set to with List parameter that will be sent to Header. It's equal to INSERT query at the relational databases model. The data set that will be added to the database is transmited at request body. For versions upper than v1.2.1, if the data sent is an array, all items in the array are added one by one, so they are added as a whole.

Headers:

APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}

Body:

{
    "BookGuid" : "2D72BCE5-2897-4C52-BD22-D5079DA5C976",
    "Title" : "Lorem Ipsum Dolor",
    "Author" : "Sit Amet",
    "IsActive" : 1
}

Body for adding as a whole at API v1.2.1 and then:

[
    {
        "BookGuid" : "2D72BCE5-2897-4C52-BD22-D5079DA5C976",
        "Title" : "Lorem Ipsum Dolor",
        "Author" : "Sit Amet",
        "IsActive" : 1
    },
    {
        "BookGuid" : "0DE4F077-6D00-4EA6-B7A0-33427FFD01F5",
        "Title" : "Consectetur Adipiscing Elit",
        "Author" : "Maecenas Faucibus",
        "IsActive" : 1
    }
]

Response:

{
    "ResponseTime": "2016-09-15T04:09:32.1757041+03:00",
    "Response": "Success",
    "ListItemId": "570d9559f6746431da1fc7ab"
}

POST /Set

It's used for updating a data object that is already added to Switch DB. In order to UPDATE a object, Listname and ListItemId parameters should be sent in the Header of the REQUEST as "List", "ListItemId", respectively, as shown in the example below. It's equal to UPDATE query at relational databases. The data set that will be edited is transmited to the database at request body.

Headers:

APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}
ListItemId: {{LIST_ITEM_ID}}

Body:

{
    "BookGuid" : "2D72BCE5-2897-4C52-BD22-D5079DA5C976",
    "Title" : "Lorem Ipsum Sit",
    "Author" : "Dolor Amet",
    "IsActive" : 0
}

Response:

{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}

DELETE /Set

It's used for deleting a data added before at Switch DB. List parameter sent remarks the list that will be deleted data from at Header and ListItemId parameter remarks the ID consisted by Switch DB for the data that will be deleted. It's equal to DELETE query at relational databases.

Headers:

APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}
ListItemId: {{LIST_ITEM_ID}}

Response:

{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}

POST /List

It's used for listing a data added before. List parameter sent remarks the list that will be do listing work on at Header. It's equal to SELECT query at relational databases.

Headers:

APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}

Count parameter under body remarks the count of items that will be listed. You can give -1 value to it for that it is limitless. Page parameter makes you wander between the pages according to the count of the items of count parameter. You can give 0 value to the first page and also make the explanations of more than one state under where parameter. There are type, column and value parameters under where parameter. The values that type parameter can be given are explain below. The name of object that will be made comprasion is given on column parameter. The value that will be made comprasion is given on value parameter.

Types Of Where

You can explain the controls of more than one state with where. The controls of states:

equal: It controls equality and equal to = operator at relational databases.
notEqual: It controls inequality and equal to != operator at relational databases.
like: It controls similarity and equal to LIKE operator at relational databases.
greaterThan: It controls greatness and equal to > operator at relational databases.
lessThan: It controls littleness and equal to < operator at relational databases.

Order parameter changes the way of sequence of the results. It supports ASC or DESC values as types. The name of object that will be sorted under by parameter.

For v1.2.1 and then

You can assign the mode of implementation of where criterions by using AND and OR types under whereType parameter.

Body:

{
   "list":"{{LIST_NAME}}",
   "count":{{ITEM_COUNT}},
   "page":{{PAGE_NUMBER}},
   "whereType": {{WHERE_OPERATOR}} // Optional
   "where":[
      {
         "type":"{{WHERE_TYPE}}",
         "column":"{{COLUMN_NAME}}",
         "value":"{{COLUMN_VALUE}}"
      },
      {
         "type":"{{WHERE_TYPE}}",
         "column":"{{COLUMN_NAME}}",
         "value":"{{COLUMN_VALUE}}"
      }
   ],
   "order":{
      "type":"{{ORDER_TYPE}}",
      "by":"{{COLUMN_NAME}}"
   }
}

Response:

{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}

POST /SendGrid/Send

It makes you send e-mails with SendGrid by using Switch API. The context of the e-mail is sent at request body. Firstly, you must introduce your SendGrid account to the system by clicking the Settings tab on the developer portal for using this method. AccessToken done this call must have Write authority.

Headers:

APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}

Body:

{
    "personalizations": [
      {
          "to": [
          {
              "email": "[email protected]"
          }
          ],
          "subject": "Mail Subject"
      }
    ],
    "from": {
      "email": "[email protected]",
      "name": "Lorem Ipsum"
    },
    "content": [
      {
          "type": "text/html",
          "value": "<b>Hello</b>, Email!"
      }
    ]
}

Response:

{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}

GET /Lists

It's used for accessing the database lists you created from the developer portal. Your API Application Key must have Administrator authority for using this function.

Headers:

APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}

Response:

{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": ["List1", "List2", "List3"]
}

v1.0 asteroid

The developer portal was ready for use.
Add, Set and List functions was prepared.
API usage reports could be received on the developer portal.

v1.1 big bang

The lists under the developer portal was given import-export supports to on the developer portal.
The distribution of CDN was activated.
The feature of creating index on the database lists was added. BETA

v1.2 cosmos

whereType operator that changes the mode of implementation of filters given at WHERE parameter to AND or OR was added.
The transition from the first chosen location to another location with the feature of database transport was easier anymore. BETA
The feature of creating index on the database lists was not beta anymore! RELEASE
A new data service was added due to your requests:
1. You can send e-mails with SendGrid by using Switch API. BETA

v1.2.1 cosmos

The feature of adding data as a whole when the data is sent as array on add function was added. BETA
Administrator authority was added to API Key Application. You can do some administrative operations by using API at your database with this authority. BETA
You could access to the lists of your database by using your application key has the administrator authority with the new Lists function. BETA
A new application and 2 new libraries were added due to your requests:
1. You can do your operations on the database easily by using Switch Database Explorer application anymore. BETA
2. Switch API Connector library that supplies the access of synchronic or asynchronic API for C# is published. You can download or use it from GitHub or NuGet.
3. Switch API Connector library that supplies the access of API for JavaScript is published. You can download or use it from Switch API CDN.

v1.3 discovery `Closed BETA`

This version is at internal test progress yet!

The feature of database transport was not beta anymore! RELEASE
2 new data services were added due to your requests:
1. You can make uploading with Amazon Web Services S3 and do some bucket management operations anymore by using Switch API. BETA
2. You can make uploading with Microsoft Azure Blob Storage and do some blob management operations anymore by using Switch API. BETA
The feature of sending e-mails with SendGrid is not beta anymore! RELEASE

Documentations

We know that you don't like reading, so we cut the documentations short...

Introduction

API Usage

API References

Changelog

v1.0 asteroid

v1.1 big bang

v1.2 cosmos

v1.2.1 cosmos

v1.3 discovery `Closed BETA`

Documentations

We know that you don't like reading, so we cut the documentations short...

Introduction

API Usage

API References

Changelog

v1.0 asteroid

v1.1 big bang

v1.2 cosmos

v1.2.1 cosmos

v1.3 discovery Closed BETA

v1.3 discovery `Closed BETA`