API

API

Goals

The intent is to have a full API for LedgerSMB, eventually. This desire has existed for a long time. To help make the discussion less abstract, we're using two cases to evaluate help evaluate the design:

• API for GL accounts

• API for Contacts, including:

  • Customers
  • Vendors

  but excluding:

  • Employees
  • Users

In general, the API should support the following functionalities:

• Creation of a new element
• Listing of existing elements, optionally
  • limited by search parameters
• Transitioning through the [document state transition diagram](Document states)

Non-goals

(todo)

Assumptions

• Any object may be subject to approval in one organization or another (not just financial transactions)
• It's best to have a single API for financial and non-financial objects
• A REST API will integrate best with existing tools and libraries

REST vs RPC considerations

REST

While a REST API probably integrates best with current thinking about web applications and the Dojo library already in use in the project in particular, there's a desire for a few RPC characteristics as well: current experience is with the existing ('old code') UI which POSTs entire documents to the server, leaving to the server to figure out which parts have changed and which parts the user does not expect to change. The design of a REST api could easily exhibit exactly this problem, putting the development team right back where they started.

Properties generally considered to be part of a REST api which can easily be re-used include:

• Grouping objects of a specific type into a collection found at a specific URI
• Retrieving objects through a URI which is a child of the collection URI
• Listing objects through the collection URI
• Searching objects with specific properties through the collection URI with a query string

not REST

The part where a REST api doesn't work well is in the application of the state transitions: The state transitions should not include any changes to a document other than the transition of state. Even more: only documents in the Locked state can be edited (as in: receive new content or have existing content 'replaced'). To this extent, it's not logical to use a REST type api to model the state transitions: the server would need to verify that nothing in the document changed except the document state. Instead, it's much more efficient to invoke an RPC call, identifying the document and the desired state transition. Done this way, the server only needs to verify the state transition's prerequisites (such as document state).

URI schema

Establishing a session

A session is established per-company. Multiple sessions may be established simultaneously.

(todo: add the session identification)

A session to a company can be established by posting to the the URI:

/company/<company name>/login

Listing available resource collections

A list available top-level resources by issuing a GET request on:

/company/<company name>/

The initial proposal discussed in this document has 2 top-level collections:

/company/<company name/
                       gl/accounts/
                       actors/entity/

where gl/ and actors/ are the modules the collections belong to.

Mapping of HTTP verbs (collection as a target)

GET    -->   (with search parameters) Retrieve a (subset) of objects in the collection
POST   -->   Create a new object in the collection


### Mapping of HTTP verbs (object as a target)

GET --> Retrieval of the named object PUT --> Save the provided object data PATCH --> Run the provided RPC command DELETE --> Delete the resource (highly unlikely to be used in LedgerSMB)