Architectural details

The Pylomer API platform can be best understood as two connected parts: the front end and back end. Both contain a representation of your business domain.

Front end

The front end is provided primarily for purposes of utility and demonstration of the capabilities of your API. While it provides a relatively convenient means of managing your application data, the display is utilitarian. All capabilities of your API are exposed, but it is expected that a web designer will use it as a reference for accessing its capabilities. It might also be used, as with Google API Explorer, as a secondary means of managing data in case, for example, the regular website is down. It provides a more accessible interface to the API than Google API Explorer.

Back end

The back end is the primary feature of the Pylomer API platform and includes your published API and data. The data is stored in Google’s Cloud Datastore. Your API is published by means of a Google App Engine application running on Google’s highly scalable and available servers.

The Google Cloud Datastore

The Pylomer API platform stores your application data in the Google Datastore, Google’s preferred non-relational (NoSQL) database. The Datastore contains collections of items, or entities. An entity is a programmed “object” which roughly corresponds to a row in a traditional relational database table or spreadsheet. It possesses attributes such as an ID, name and creation date specified for it at design time. Each entity has a Kind, such as “Contact”, “Event” or “Message”. Unlike a SQL table, new attributes can be specified on the fly. So if you later determine that a customer record needs to contain a birthday attribute, the attribute can be simply added to new customer records on a case-by-case basis without affecting older records such as would be the case when adding a column to a relational table.

Furthermore, any entity in the Datastore can be associated with any other entity by means of this mechanism. So if the customer’s supervisor also happens to exist in your contacts, a “boss” field can be added the the customer entity with no impact to the rest of the system. In essence, the Datastore is more like a set of folders than of “tables” or “sheets”. Anything that can be represented in an RDBMS can be represented in the Datastore. The Datastore can contain much that is difficult or impossible to store in a SQL database. Not only can attributes be added to entitites “on the fly”, but entire records may be included in entities, rather than storing them in their own tables with all the overhead. Instead of being locked into a rigid table structure, entities in the Datastore have the flexibility of folders in a file system rather than the tables in a MySQL database. Software can be created to reflect this.

Google Cloud Endpoints

The Pylomer API platform publishes an API by interacting wth Google Cloud Endpoints within an App Engine application. Cloud Endpoints allows development of JSON web services on App Engine. It provides a way to directly interact with your cloud-based API using the JSON interchange format. The JSON interchange format has the advantage of being concise and human readable.

Google’s Platform as a Service (PaaS) infrastructure provides a framework for accessing the contents of the Datastore over plain HTTP connections such as commonly used to load web pages. In fact, if not for the authentication requirement, any data stored in your application can be accessed just like a web page with its own URL.

For example, if a vehicle you have rented out has a cellphone signal amplifier, the manufacturer might be viewed by visiting the following URL:

http://supercars.com/inventory/vehicle123/upgrades/cellphone

The record might appear as such in the browser in its JSON format with easily-identifiable attributes:

{
 "id": "qca21_amp",
 "description": "Qualcomm cellphone amplifier",
 "kind": "VehicleUpgrade",
}

Data can also be created, updated and deleted in this manner. All methods of the HTTP protocol are supported, and without depending on a specially-coded client app. This highlights the advantage of the Pylomer API platform and the web services application model.

Endpoints Proto Datastore

The Pylomer API platform makes use of this library, provided as a standalone library by a Google Cloud Endpoints engineer. EPD is just a helper library of functions to simplify developing Endpoints applications. It takes care of much of the work of converting Datastore entities to and from their JSON representation, as described above, when traversing the Internet. While EPD makes the common use cases simpler, it also somewhat restricts the options available.

An example would be requesting a list of your customers who work for a given company. A natural representation of this request would be:

http://mysuperapi/companies/acme/customers

With EPD, however, the request must take a less elegant form:

http://mysuperapi/customers?company=acme

This is more in line with requests on traditional SQL-backed servers. In practice, the restrictions are outweighed by the advantages of easier, less error-prone development.

Entity Structure

In addition to any attributes defined at design time, all Pylomer API platform entities are created with five default attributes: ID, title, description, owner and date created. Any attributes except ID and date created may be later modifed. Title and description can be set to reasonable values and serve as a limited form of metadata about the entity.

Entity IDs

An entity ID can be any sequence of alphanumeric characters. It must be unique within within the kind of the entity. For instance, there can be no two companies with the ID “acme”. But there can be a Company and a Product with the ID “spam”.

The decision to set the ID of an entity to a user-defined value was made in order to simplify initial development. An entity ID must be unique within its Datastore kind. Other similar systems automatically create entity IDs which are guaranteed to be unique within their kind. Manually specifying the ID enables an entity to be more easily recognized across the system and eases the job of the web designer in creating drop-down selection lists and menus, etc.

Other entity attributes

Other attributes are specified for the entity in the data modeling stage of the project and thereafter and can be set according to the data model specifications.