Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

toc-local

Introduction

This page provides some guidelines for server programmers to bring some consistency to the services APIs.

Service Names

Although service names can be anything, there are some common practices that make it easier for users two switch between servers and have reasonable expectations.

NameExplanation
addAdd an item to an existing pool.
createCreate an "object".
destroyDestroy an "object".
getGet an item from a pool.
listProvide a simple list of item in a pool. Should be a strings, one per line, which would correspond to some key/name of the items. list should be used for the most common items being listed. See listX.
listXProvide a simple list of items in a pool, for specific, non-default pool. Should be strings, one per line, which would correspond to some key/name of the items.
putPut/replace/update an item into a pool.
removeRemove an item from a pool.
statusProvide a summary of state information in a table format. Other formats may also be supported (csv, json, key-value).

Input and Output Formats

csv - simple, string, tabular data

json - Many/most services will be transaction-oriented (request-response). This requires no communication protocol over the input and output descriptors but simple sending and receiving using commonly used and understood formats.

CSV

CSV is composed of simple strings separated by a comma separator typically used for tabular data.

In some cases, CSV can use quotes to delimit the strings value extents and allow for contained commas. Unquoted values can be treated as non-string values (e.g., numbers).

JSON

JSON is for hierarchical, structured, typed (object/map, array/list, string, number, null) datakey-value - . Many languages provide support for encoding/decoding JSON.

Key-Value

KV is for named, multi-value per item data. "=" or ":" are used as the separator between the key and value; the newline as the separator between key-value items; and a blank line as the separator between sets of key-value items.