Basic Design Principle of CPNaaS

CPN Tools Logo Cloud Syntax CheckCPNaaS is my new under-development API for colored Petri nets-as-a-service, i.e., a web-API for tools.

At the core of the API is a RESTful web-service.  This just means that each resource has a unique URL, which is manipulated as if it were a web-page.  Web-pages are normally just obtained for reading (GET), but may also be sent information to generate extra information (POST).  Tools for editing web-pages can additionally upload new pages (PUT) or delete out-dated ones (DELETE).

Models and all information pertaining to them is created using this simple principle.  In addition to this, we often have collections of elements (multiple nets, multiple pages in each net, multiple places on each page, etc).  For this reason, most operations come in quintuples:

Screenshot 2015-05-24 14.43.30

The first (GET) lists all resources of the given kind, the second (POST) creates a new resource.  These are not specific to one particular resource.  The third call (GET) gets all information about a particular resource, the fourth (PUT) updates it, and the fifth (DELETE) deletes it.

In the figure above, we see that this patters is followed for nets for a particular user, for pages of a particular net, and for places of a particular page in a particular net.  Names in curly brackets are place-holders and are replaced by identifiers returned by the API.  This means that the first GET with return a list of all identified resources including at least an identifier to be used to address each particular resource.  The second POST call will take a number of resource-specific parameters (like name or place type) and return an id of the newly created resource.  Resource identification is performed using path parameters while all resource parameters are passed as form POST parameters; here’s the parameters for creating new places:

Screenshot 2015-05-24 14.52.25

Clients can specify optional unstructured parameters using JSON in the optional body part.  These parameters are stored along with the resource.  This makes it possible for graphical editors to store information such as color or size of a place, or for extension APIS to store information that allows them to perform their work (they can for example tag a node as generated or tied to an external service).  Such values should be name-spaced by the creating application to avoid accidentally over-writing values set by other applications working with the same model (e.g., a graphical editor and an analysis application or extension API).  Of course some values may make sense to share (such as graphical layout information), but this is not part of the CPNaaS specification.  Instead, we expect de-facto standards to prevail, where guidelines for shared information emerge as needed.

The third GET call will return information about a given resource.  It returns all the resource-specific parameters as well as the optional extra parameters.

The fourth PUT call takes the same form as the POST call used to create a resource, except it also takes a resource identifier.  It updates the resource with new information

Screenshot 2015-05-24 14.52.51

The fifth DELETE call just deletes the resource so it is no longer available.

Most APIs will specify that the POST, PUT and DELETE call requires a specific permission, write, to execute.  This makes it easy to grant read-only access to applications.  This is for example useful for sharing models openly on the internet of inclusion in a paper.  This feature can also be used to grant permission to third parties that are not entirely trusted, and to force application makers to deal with the fact they may not have write access to models.

CPN Tools Logo Cloud SnapshotsThe point of forcing applications to be able to deal with read-only models is in particular because some APIs only provide a reduced set of the 5 functions for each resource kind.  For example, the Snapshots API provides a read-only view of previous revisions of a model:

Screenshot 2015-05-24 15.09.36

Any API which only relies on a read-only view of models can immediately deal with snapshots; instead of being given a /nets/{netId} URL to a model, they are given a /nets/{netId}/{snapshotId} URL and can address everything using identical structure as a “live” current model.  A model shared in a paper should never be the live “current” model, but rather a particular snapshot made for the paper.

CPN Tools Logo Cloud SimulationOther calls either do not make sense for all methods, for example if the resource is a computed one and not a user-created one.  For example, the Simulation API gives read-only access to the instance hierarchy, which is implicitly specified by a sub-page relation between pages.

The simulation API also gives access to the current and initial state of a model.  This a.o. comprises the current and initial marking of places.  We cannot create new “current markings” explicitly, but we can read the current and initial marking and change the current marking as illustrated by this fragment of the Simulation API:

Screenshot 2015-05-24 15.15.08

That concludes the introduction to the basic API architecture of CPNaaS: the 5 calls, the shared structure of POST and PUT with optional parameters as first-class citizens, and explicit read-only access. Follow the development of CPNaaS on our Facebook page or take a look at the APIs on the prototype API specification page.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.