-
Notifications
You must be signed in to change notification settings - Fork 4
APISpec
This page gives an overview of the API
NOTE: This Lookup Service API is not stable yet and may undergo changes based on reviewer comments/suggestions.
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:
- Record Management
- Query
- Subscribe
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
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
The Record API consists of:
- renew
- delete
- accessing a service
- accessing a specific key-value in the service.
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.
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.
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.
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.
Starting from v3.0, users can directly use the elasticsearch API to query the lookup-service. For details, refer here
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.
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.