APISpec

Sowmya Balasubramanian edited this page Aug 8, 2018 · 13 revisions

This page gives an overview of the API

API specifications

NOTE: This Lookup Service API is not stable yet and may undergo changes based on reviewer comments/suggestions.

Introduction

Simple Lookup Service provides a REST/JSON API to the clients. This allows the API to be easily accessed from nearly any language or by using CLI tools such as curl.

sLS registers records.

The API has been divided into 3 main sections:

  1. Record Management
  2. Query
  3. Subscribe

Record Management

The Record Management API itself has been sub divided into

  • Registration API - to register records
  • Record Management API - to access, renew or delete a record

Registration API

DESCRIPTION: Register a service

URL: /lookup/records/

OPERATION: POST

PARAMETERS: none

REQUEST: application/json The request contains the full list of key/value pairs that makes up the registration. While any key may be used, some key are defined:

REQUEST BODY: The record to be registered.

Mandatory keys

type: string, The type of record. Users can use custom values or pick from the well-defined ones. The well-defined ones are "service", "host", "interface" and "person". Users can also define their own record types.

Example JSON Registration format:

{“<key1>”: ["value 1"],“<key2>”: [“<value2.1>”,“<value2.2>”]}

Note that each key in the list of key/value pair must be unique.

RETURNS: application/json Returns the set of key/values as they have been stored in the LookupService. Additional key/value pairs added by sLS are:

uri: URI of the created service expires: The time that the registration is valid. This is the final value. It may or may not be what the client requested. state: the state of the record (registered)

ERROR CODES:

200: Created
400: Unspecified error/Bad Request
401: Unauthorized(future)
403: Record already exists
415: request is not application/json
500: Internal server error

Record API

The Record API consists of:

  • renew
  • delete
  • accessing a service
  • accessing a specific key-value in the service.

Renew

DESCRIPTION:  Renew an existing service

URL: lookup/<record-id>

OPERATION: POST

PARAMETERS: none

REQUEST:  application/json Mandatory key

privatekey(future implementation): string, UUID created and provided by the client. privatekey is used by the client when renewing or deleting a service.  

Optional keys

ttl: string, The time interval for which the client wants the registration to be valid. The server may or may not grant the request. Duration is expressed in ISO 8601 format.

JSON format: [{“privatekey”: “uuid”}, {“ttl”: “PT2H6M5S”}](“”]]

RETURNS: application/json Service record that was renewed

ERROR CODES:

200: Renewed
400: Bad Request
401: Attempt to renew a service registered with a different privatekey than the key/value pair provided in the   request. (_not yet implemented_)
404: Service does not exist.
500: Internal server error.

Delete

DESCRIPTION:  Delete an existing service

URL: lookup/<record-id>

OPERATION: DELETE

PARAMETERS: none

REQUEST:  application/json

Mandatory keys

privatekey(future implementation): string, UUID created and provided by the client. privatekey is used by the client when renewing or deleting a service.

RETURNS: application/json

Service record that was deleted

ERROR CODES: 200: Deleted 400: Unspecified error/Bad Request 401: Attempt to delete a service registered with a different privatekey than the key/value pair provided in the request. 404: Service not found. 500: Internal server error.


Access

DESCRIPTION:  Access all the key/value pairs associated with the record

URL:  lookup/<record-id>

OPERATION: GET

PARAMETERS: none

REQUEST:  none

RETURNS: application/json Returns key/value pairs that are associated with the record

ERROR CODES: 200: Ok 400: Unspecified error/Bad Request 404: record does not exist 500: Internal server error.


Access a key/value

DESCRIPTION: Access a specific key/value pair of a record

URL:  lookup/<record-id>/<key>

OPERATION: GET

PARAMETERS: none

REQUEST:  none

RETURNS: application/json Returns key/value pair that is associated with the record and the specified key.

ERROR CODES: 200: OK 400: Unspecified error/Bad Request 404: key or record does not exist 500: Internal server error.


Query

The QUERY API uses GET method and all the key-value pairs are passed as parameters in the URL. This is suitable for queries that do not contain any sensitive information as parameter and also if the size of key-value pairs is not too big. This API always results in querying the back-end database for latest records. An advantage of using this method is that intermediary HTTP proxies can cache data. A potential issue that may or may not be a huge concern is that the size of URL is not well-defined (some old servers may accept only 200 bytes whereas the more practical value is 2K bytes).

DESCRIPTION: Queries the lookup service and returns service records that match the query.

URL: /lookup/records

OPERATION: GET

REQUEST PARAMETERS: One or more optional keys and their values may be specified. If no key-value is specified, all the services are returned.

All key-value pairs are considered to be unique. If there is more than one value for a key, the multiple values should be separated by a comma.

operator: ALL | ANY. If ALL is specified then records containing all the specified key-value pairs are returned. For ANY, records matching at least one of the specified key-value pairs are returned. Default is ALL.

Example: /lookup/services?key1=value1&key2=value2&operator=ANY

RETURNS: application/json list of service records with one or more keys.

Example Format:

{result: [
             {   key1: “<value1>”,
                 key2: “<value2>”,
                 key3: “<value3>”
              },
              {   key1: “<value1>”,
                  key2: “<value2>”,
                  key3: “<v3>”
               },
             {    key1: “<value1>”,
                  key2: “<abc>”
               }
           ],
next: “<some-url>”
}

ERROR CODES: 200: Ok 400: Bad Request 500: Internal server error.

Support for metacharacter

The Query API allows the special character * at the beginning or end of the values.

For example, to search for values that begin with abc for a particular key, say key1, use the following notation: http://<somehost>/lookup/services/?key1=abc*

To search for values ending with abc,

http://<somehost>/lookup/services/?key1=*abc

Currently, we support only prefix and suffix matching and do not allow other substring searches.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.