Page Comparison

Many of the PWS web services fall into the category of CRUD (Create, Read, Update, Delete) services. That is, they are concerned with adding, editing or deleting data in Projector. A typical set of CRUD services includes:

...

• Reference Structures
• Summary Structures
• Detail Structures
• Element Structures
• Summary Element Structures

Each structure has a specific purpose or specific purposes, and generally adheres to certain rules and conventions as detailed below.

Reference Structures

Reference Structures uniquely identify a specific instance of an entity (for example, a project reference structure identifies a specific project). Where specific instances of an entity may be uniquely identified by multiple different keys, the reference structure will provide each alternative means of identification (For example, projects may be identified by an internal identifier, a unique identifier or the project code – the project reference structure offers all three means of identification).

...

Note on internal identifiers: Most reference structures contain an internal identifier as one of the alternative means for identifying instances. Internal identifiers are mutable, and while not likely to happen frequently, they are subject to changing over time. As such, they are typically reserved for internal use and by default, the values returned by web services for internal identifiers will be NULL and any internal identifiers specified as inputs to web services will be ignored. Unique identifiers, by contrast, are immutable and should be used by web service consumers instead of internal identifiers.

Summary Structures

Summary structures inherit from reference structures and are typically used in services that return lists of entities. They include a small number of key attributes that are generally considered useful in lists. The size of the structure is intentionally kept pretty small to reduce the size of web service responses containing lists of these structures.

Detail Structures

Detail structures inherit from summary structures and are intended to contain (directly or via inheritance) the complete set of attributes describing the underlying entity. These structures are used as input to services that save changes to instances of an entity, and are part of the response from services that retrieve instances. This makes it easy to use the web services to make changes to an instance, as the same structure retrieved by one service call may be edited and passed back up to a different service to save the changes.

...

Nullable vs Non-nullable Attributes

Generally, the save services are implemented such that leaving an attribute NULL in the detail structure is an instruction to leave the current value of the attribute unchanged. This works file for non-nullable attributes, as NULL is not a valid value for the attribute itself, but this is not the case for nullable attributes. For nullable attributes, there needs to be a way to set the value, NULL the value out or leave it alone. Nullable attributes have a corresponding clear flag that facilitates this as follows:

Grouped Attributes

In some cases, an entity may contain a group of two or more attributes that are related in such a way that it makes more sense to treat the group as a unit rather than independently. In these cases, where a clear flag is appropriate, it will typically apply to the group as a whole.