Universal API

The Universal API is an abstraction layer over different storage backends, also known as persistences. This abstraction supports legal and business processes with documents functionality regardless of where or how the document is actually stored.

Persistences

A persistence is the storage backend for documents. It enables storage agnostic processes and integrations.

In a tenant each persistence type can only be used once.

A tenant-wide default setting determines which persistence is used. Applications can use access different persistences explicitly per request.

Not all persistences support the same functionalities. The following table explains what capabilities the individual persistences support.

The Universal API provides document capabilities across supported archives or persistences. Not all persistences are equal. There are schematic and behavioral differences between them. Some are minor (different length of version numbers) but others are major (e.g. categories dont have an ID and only a name). Given these differences, the Universal API strives to offer a harmonized facade for all supported persistences.

We strive to support the greatest common denominator where it makes sense. We dont let outliar differences dictate the overall standard of the Universal API. We accept that certain persistences might not support all capabilities to the fullest. We expect the adapters of these persistences to reconcile differences to the best of their abilities and throw exceptions where they cannot. We accept that these persistences behave differently at runtime.

It becomes easier to

• establish a standard of document capabilities, because we are not limited by the weakest supported persistence
• use best practices, because they benefit the majorify of persistences.

It becomes more difficult to

• predict runtime behavior, because depending on the configured persistence, the APIs might behave differently (we could mitigate this with a limitations API in the future)
• write universal code, because more exception handling has to be implemented.

Contexts

Contexts provide metadata-based grouping of documents. Documents can be associated to a context. Contexts are for example case/matter, legal category, or participant.

Other applications dealing with documents are responsible to maintain context representations of their container objects within STP.Documents.

The availability of context types is determined by the used persistence. We assume that all supported persistences have at least one context type comparable to a “matter” (stp.doc.matter).

Versions

Each document maintains a version history. A version captures the state of a document’s content (including renditions) at a specific point in time.

The latest version reflects the most current state.

All versions are ordered chronologically.

Renditions

A rendition is a representation of a document version, such as:

stp.doc.original – the original content

stp.doc.preview – a display-ready preview

Applications can define custom renditions. They can be read by all applications, but written or deleted only by the creating application.

Named Values

Named values attach additional metadata either to the entire document or a specific version. These values can be used as custom annotations, flags, or auxiliary data.

Events

Changes in the persistences can be observed via events (e.g. document uploaded, version updated, etc.). Other STP applications can subscribe to these events.

APIs

The Universal API consists of multiple APIs. Details about their endpoints can be found in these Open API specifications:

• Upload API
• Download API
• Metadata API

For dotnet we also provide the STP.Documents.Client nuget package via our private technology partner nuget feed at STP.TechnologyPartner. Learn more about working with the NuGet registry.

Example code can be found at STP.Documents.Example.

How to get started building?

To access STP Cloud APIs, you need to register your application with us. This will allow your application to acquire access and refresh tokens to access STP Cloud APIs on your users behalf.

Please contact us at support@stp.one to initiate your application registration. Please provide details about what kind of application you are building and how it simplifies your users’ legal work. During the onboarding process you will also need to accept our technology partner agreement.

Afterwards you will get access to our private technology partner nuget feed at STP.TechnologyPartner, where you can find all our packages.

Please note that Documents customers must first be activated and enter into an additional licence and usage agreement before they can use the API with your product. Alternatively, you can apply to become a Marketplace Partner and make your solution available to all Documents customers under a cooperation agreement.