Resources are at the heart of the Eulerio Data Platform. A resource is an entity defined by a specific type with associated data and relationships to other entities. It is also defined by a set of methods that are allowed to operate on its contained data. Typically, an application will define and manage multiple resources that represent unique objects or actors in a workflow or process that encapsulates the application logic.

When you define a resource in Eulerio, you provide the details of the resource such as it's unique name, it's attributes, and what methods it exposes for acting on its data. The meta-data you provide when describing your resource is based on JSON Schema. It uses a familiar and standard paradigm to configure and represent a data entity in the Eulerio Platform.

Once your resource has been defined in Eulerio, you can use the resource's methods to create, modify, and delete instances of that resource type. The allowable methods are standard REST requests over HTTPS and they can be called using vanilla methods supported by nearly all programming languages, platforms, and data access tools. You can manage your data and retrieve the stored values for every resource using a standerd GET request. Data is returned as collections or as specific instances of a particular resource identified by values of the resource's attributes.

Data management in Eulerio is comprised of two operations: Resource definition using a standard JSON schema and data population using standard protocols. In a nutshell, this is resource management in Eulerio.

The url prefix is used to uniquely identify your endpoints in Eulerio. Before you can define any resources, you must set your url prefix. This prefix is permanent and cannot be changed once set. It is unique to your Eulerio account. It is also the url path used when querying your database.

Setting the prefix

When you navigate to the Resources page through the user menu, you will be requested to set the url prefix value if it has not yet been set. Once set, this page will no longer be displayed and you will be directed to the Resources page for every subsequent navigation.

Url prefix format

The url prefix can contain alphanumeric characters and special characters like dash or underscore. Other special characters are not allowed. When you enter a url prefix, it will be validated and any validation errors will be returned to the UI. These errors must be addressed before the url prefix is accepted.

Resources are entities describing your data. They have attributes that capture data and methods that permit modifying the underlying attribute values.

Creating a resource

You create a new resource in Eulerio by navigating to the Resources page and clicking the "Create Resource" button.

Defining resource settings

Settings for the resource are: name, description, and allowed methods. The name uniquely defines the resource. Multiple resources cannot share the same name and the name must be url safe. The value entered will be validated for uniqueness and format before it is saved.

The resource description is a short summary for the resource.

The methods are the HTTP methods allowed on the resource. You can control which methods are exposed by your REST endpoints for the resource.

You can assign the resource for an existing group or create a new group for the resource in order to organize your resources.

Once a resource has been created you can modify its description, allowable methods, and schema definition. The resource name cannot be modified. By modifying the methods on the resource, you can update and control access to your resource data. Modifying the schema will apply to all subsequent requests after modification. Stored data will not be affected by the schema update.

Modifying a resource

From the Resources page, you can modify the resource by selecting the edit icon on the resource record displayed in the list of resources.

Saving modifications

After the resource details have been modified, clicking "Save Resource" will persist your changes.

Resources can be deleted in Eulerio. Deleting the resource will not only delete the resource definition, but it will also delete the data saved for that resource. Please proceed with caution when deleting a resource, as the action is irreversible.

Deleting a resource

A resource can be deleted by selecting the "Delete" icon on the resource record displayed in the resource list.

Confirm delete

You will be asked to confirm your deletion request. The action is irreversible.

Resources are defined in Eulerio using a schema derived from JSON schema. You can read more about JSON schema here.

Defining your resource

The best way to start defining your resource is through an example. We will define a resource that describes a person. The attributes we would like to collect about the person are: first name, last name, and age. The JSON representation for a person object is:

In order for Eulerio to process data for the person object, we must define a schema describing the person object using JSON Schema. The schema below defines the person object:

At the top level of the schema, we assign a name for the object through the keyword "title". The "title" attribute is the name of the resource. In our example, the resource name is "Person". Below the "title" keyword, we can add an optional "description" keyword and assign a short description of our object as the value. However, for this example we will skip the description.

The next keyword we will add is the "type" keyword. The "type" keyword is used to restrict the JSON data to a specific type. In essence, the "type" keyword is used to describe the format of the data that will be passed in JSON data conforming to the declared schema. In our example, we restrict our "Person" object to a "type" of "object".

Looking at our sample JSON Person object above, we see that our object has attributes: firstName, lastName, and age. In order to describe these object attributes in our JSON Schema, we use the "properties" keyword. The value assigned to "properties" is an object containing a declaration of each of the object's attributes and the data type accepted as values for those attributes.

Finally, we add a constraint to our JSON data through the schema. We add the "required" keyword on the Person object and declare an array of the Person atrribute names that must be present in a JSON representation of our Person object. If any of these declared attributes are missing, JSON data restricted by our schema will be invalid and any processes attempting to handle this data will fail.

Allowable types

JSON schema supports the following data types when declaring a "type" for JSON data:

• object
• string
• number
• integer
• array
• boolean

object

A JSON object typically contains a set of attributes or properties that describe its state. When declaring an "object" type in JSON Schema, the "properties" keyword is used to declare and describe the object's attributes. For instance:

Sample JSON object data:

string

The string type in JSON is a sequence of characters. When used in a JSON object, the string must be enclosed inside double quotes.

Sample JSON string data:

number

The number type is used to declare floating point or decimal numbers.

Example number JSON data:

integer

The integer type is used to declare whole numbers.

Example JSON:

array

The array type is used to declare a collection of items. When declaring an array type in JSON Schema, the "items" keyword is used to describe the data types contained in the array. The data types can be any of the allowable types in JSON Schema.

For instance, the following JSON data:

is described by the following schema:

boolean

The boolean type is used to describe data with only two possible values: true or false.

Sample JSON:

Allowable formats

JSON Schema permits the declaration of string formats to restrict the allowable values for a string type property. One type of format of particular interest is the date-time format. In Eulerio, all dates and times are represented by a string adhering to the standard ISO 8601 format.

To restrict string values to the date time format in JSON Schema, you declare a format on the string type property. For instance, a date of birth property can be declared as:

Sample valid data for a date-time restricted string type:

Additional string formats are supported in JSON Schema. They can be declared to ensure that the value passed for the string type property conform to the declared format.

Unique properties

Adding a "unique" keyword to your schema allows you to specify which properties ensure uniqueness of your data. The "unique" keyword accepts an array of property names declaring which attributes must have unique values in the data collection.

In the above example we have specified that the attribute "email" must be unique for every record. The following error will be thrown if the same email is used for two records.

Schema Validation

When declaring your data schema to describe your data, the schema must conform to the conventions of JSON Schema. If your schema fails to validate against JSON Schema, validation errors will be raised. These errors will have to be addressed before you can access your resource in Eulerio.

Unsupported attributes

Eulerio's data schema is based on JSON Schema. It supports the majority of types and attributes included in JSON Schema. However, there are exceptions. The following attributes/types are not supported and will result in a validation error.

Your resources and data are secured using secure protocols and managed credentials. All communications with Eulerio are conducted through encrypted channels between authenticated parties.

All data access requests are made over HTTPS which protects against various types of attacks and against eavesdropping or tampering with the communications. All requests are also authenticated by digital certificates signed by a trusted third party provider.

Resource requests are further authenticated against credentials you create in Eulerio. You create and assign encrypted keys for application clients to present in order to access your resources. These keys are unique to your account and they are managed using Eulerio's key management interface. When a key is presented for resource access, the key is validated to ensure that it is active and has been issued by the Eulerio platform.

All communications with Eulerio are encrypted. All endpoints are accessed through HTTPS, which ensures that client server information exchange is fully encrypted.

HTTPS request

Client requests are handled through HTTPS. Any requests from clients through HTTP are automatically redirected to HTTPS. Please ensure that your client supports "follow-redirects" if accessing a resource through HTTP.

Example client request

You can quickly test your resource requests using simple command line tools like curl, which is available for all platforms or online visual tools like Postman. Below is an example of a resource request using curl.

All requests to Eulerio are authenticated against user credentials. In order to access a resource, an client access key must be presented to authenticate the request.

Creating an access key

You create an access key by clicking "Generate Key" on the Access Key page. A new unique key will be created for use in authentication.

Copying key

You can copy the an access key to your clipboard by clicking the copy icon on the access key record in the list of access keys.

Using the key

You pass the access key in the header of your request. The header name is "Authorization" and the value is set to "Bearer <Access Key>".

Deleting access key

Access keys can be deleted by selecting the keys to delete and then clicking the "Delete" icon. Deleting keys will immediately invalidate any clients still using the deleted access keys.

The following examples demonstrate how to make a secure request. All requests are made using HTTPS and they must pass an "Authorization" header with a client access key in order to complete the request. Although the examples are written in curl, it is can easily be translated to method calls in any programming language using its native implementation.

GET request

POST request

PUT request

PUT requests update a resource. The request url adds the resource id at the end of the resource url. The resource id is used to identify the resource that is being updated.

DELETE request

Through Eulerio's dashboard and activity charts, you can monitor usage across all your resources. You can view the number of requests per resource and the data storage allocated to hold your data. This information will allow you to monitor the activity against each individual resource and it will enable you to plan and manage your resource allocation accordingly.

You can also view the number of requests made per user agent or access key and the most active REST endpoints for your resources. Using this information, you can track which application feature provides the most utility and which client interface is the most popular for your application.

The Eulerio platform provides the tools for monitoring your resource usage, which can assist in the design of your application and it can inform future application considerations.

You can monitor resource usage through Eulerio's dashboard.

Monitoring requests

The number of total requests for the month as well as the number of requests for the current day is displayed in the dashboard. You can track the number of requests processed against your resource usage monthly quota.

Storage

The number of resources and the amount of storage used by your resources is displayed against your allocation. The storage limit and number of resources does not reset per month. If you are encroaching your storage limit, you can reduce the amount of storage needed by deleting resource data or you can request an increase on your storage limits.

Eulerio's usage dashboard displays useful information about activity against your resource. You can use this information to understand user behavior and inform product decisions around your application.

Resource activity

Activity against a resource is displayed as the number of requests made per resource. You can use the date filter to change the data range for which you would like to view the request activity per resource. You can also use the chart filter on the request histogram to sort the requests per resource view.

User Agents

Calls made per user agent against resource endpoints is displayed in a sortable table. The list displays the count and percentage of all calls made by the given user agent.

Most Active Resources

The most requested endpoints are displayed sorted by total number of requests made against that resource.

The time history of the number of requests made per resource group is displayed in the dashboard so that you have a time lapse view of resource activity.

Activity Chart

The resource activity chart displays the number of requests processed per resource group for the preceding week up to the current day. The number of requests are binned in hourly increments. The data point displays the aggregate count of requests received per hour.

After you have defined and created your resource and you have enabled its access methods, you can manage the assocated resource data using its REST interface. All access methods are exposed through a REST API and you issue API requests using standard HTTP methods.

Standard GET requests against the resource's unique URL are issued to retrieve resource data. The GET endpoint also allows for data filtering by defining conditionals against the resource's attributes. These conditionals are passed through the URL in the form of query parameters.

HTTP POST and PUT requests with JSON request bodies are used to create and update resource data. A new instance of a resource is created by POSTing JSON data to the resource URL. A PUT request to the resource URL with JSON data is used to update resource data.

Eulerio also provides DELETE HTTP requests to delete resource instance data. DELETE requests are irreversible and the data for the requested resource will be deleted from the database.

All resources defined in Eulerio are accessible through a standard REST API. Data is exchanged through HTTPS and request and response data is formatted in JSON. Any errors that arise when using the resource REST APIs are returned with a corresponding HTTP status code and a JSON message containing a short explanation of the error encountered.

REST API

Resource requests are issued against a standard REST API for each resource you have configured. Allowable methods on resources are: GET, POST, PUT, DELETE. You can set which methods are accepted for each resource you define.

Resource Url

The resource url corresponding to the resource is a path concatenating the resource url prefix and the resource name.

Content type

All responses in Eulerio are returned as JSON. The request object should pass an Accept request header set to "application/json" to communicate to the server that it can understand content of type JSON. When sending JSON data with a request, the request header must include the request header, Content-type, set to "application/json".

Request authentication

Because all resource requests require authentication to access the data, the HTTP header, Authorization, must be passed with a value set to "Bearer <Access Key>.

GET request

A GET request to the resource endpoint retrieves a collection of JSON data corresponding to that resource. For example, a GET request for a "writer" resource would return a collection of "writer" JSON objects.

Paging

By default, all GET requests against a collection return a maximum of 50 records. In order to retrieve the whole collection, you should page through the results using the request parameters, page and limit. Page corresponds to the current starting point for retrieving the collection and limit indicates the number of records to return. For instance, attaching page=2 and limit=50 query parameters to a GET request will return record numbers 51-100 for the collection.

POST request

A POST request against the resource URL creates a new instance of the resource. The POST request must contain a JSON request body containing resource attributes and the corresponding attribute values. If the request body passes validation a new resource is created and returned in the response. The new data object will automatically be assigned a unique id to identify the object data. An example JSON request body to create a new writer and add to the collection of the writer resource:

You can create multiple resource instances in one POST request by passing an array of JSON objects in the request body.

PUT request

The PUT request is used to update the attribute values of a resource. The request must include a JSON body containing the attributes with corresponding values for the data to be updated. The following PUT request body will update the writer with id "writer1". Note that the request url contains the id of the resource record to be updated.

DELETE request

A DELETE request including a JSON list of resource ids in the request body results in the deletion of the data of objects with corresponding ids. The data is removed from the database and the operation is irreversible.

Filtering result sets

The collection returned by a GET request can be filtered by criteria set against a resource's attribute values. You pass filters to the resource endpoint through a query string containing parameter/value pairs. The parameter name consists of the resource target attribute concatenated with the filter name contained inside square brackets. The parameter value is the filter criteria. The supported filter options are:

[eq]- equals filter. Checks if the named attribute is equal to the specified value.

[ne]- not equal to filter. Checks if the named attribute is not equal to the specified value.

[gt]- greater than filter. Checks if the named attribute value is greater than the specified value.

[gte]- greater than or equal to filter. Checks if the named attribute value is greater than or equal to the specified value.

[lt]- less than filter. Checks if the named attribute value is less than the specified value.

[lte]- less than or equal to filter. Checks if the named attribute value is less than or equal to the specified value.

[in]- in filter. Checks if the named attribute value is in a list of specified values.

[not-in]- not in filter. Checks if the named attribute value is not in a list of specified values.

[startwith]- starts with filter. Checks if the named attribute value starts with the specified value.

Filtering by Date and Time

When filtering by date or time, the value to pass for the filter criteria is the number of seconds that have elapsed since epoch for the date or time you wish to filter on. For instance, if you would like to define your filter for July 15, 2000, the value to pass is 963619200. You can find a handy utility for converting dates and times to epoch time at EpochConverter.

Combining Filters

It is also possible to combine multiple filters on multiple named attributes. However, there are some restrictions on certain filters. Specifically, filters [gte], [gt], [lte], [lt], [startwith] can only be used with a single attribute.

Sorting result set

The collection returned by a GET request can be sorted by a resource's attribute. You pass the "sortby" parameter to the resource endpoint through a query string. The "sortby" parameter supports two filters:.

[asc]- sort ascending order. Sort result set by specified attribute in ascending order

[desc]- sort descending order. Sort result set by specified attribute in descending order

Retriving a single object

For every resource, a single instance of the resource can be retrieved by issuing a GET request against the resource url followed by the unique id of the object to be retrieved. A GET request to the following url:

will return:

All API responses are standard HTTP responses with corresponding status codes and JSON response bodies.

Status codes

Eulerio returns the following status codes:

• 200 - the request was successfully handled
• 204 - the request succeeded with no content to return.
• 301 - the request has been permanently moved to another URL.

Response data

All responses are in JSON format and typically return the resource data as a collection of objects or an object corresponding to the requested resource. For instance,

or

Errors can arise for a variety of reasons. Badly formatted requests, invalid request data, and network errors are just some of the types of errors that can occur in an application. When an error is encountered in Eulerio, an error response is generated containing a HTTP status code and a message body describing the error.

Status codes

Eulerio returns the following error status codes:

• 400 - the request failed due to client error.
• 403 - the request is unauthorized.
• 409 - the request failed due to a conflict with the target resource.

Error messages

Errors are returned as JSON objects. The object contains two attributes: status and errors. The attribute status contains the HTTP error code and the attribute errors contains a short description of the error encountered.

For all your configured resources, you can generate reports encapsulating the data held for each resource type in the database. Using Eulerio's report builder you can select the attributes and configure filters against those attibutes to return in your reports. The data can be queried and viewed in Eulerio or it can be exported to a CSV file for download.

You can save your reports in Eulerio and you can view your list of reports on the report landing page. You can manage your report list by creating new reports or deleting existing ones. You can also modify a saved report in order to generate an updated view of your resource data.

Generating reports are an integral part of data management. Using Eulerio's reporting tools you have complete access to your application data.

Reports provide a view into your resource data. You can use Eulerio's reporting tools to generate custom queries against resource data. The generated report can be saved and downloaded as a CSV file.

Creating a report

From the Report page, click the "Create Report" button.

Enter the report name. The name does not have to be unique. Multiple reports can share the same name.

Save the report

The report will be saved under the entered name.

The Report page displays a list of saved reports. Rolling over the rows of saved reports will highlight menu options for managing your reports.

Edit a report

Clicking on the Edit icon will open the Report editing dialog.

Delete a report

Select the reports to be deleted and then click the Delete icon.

Reports in Eulerio are saved queries. You can view the report data by running the report.

Run a report

Click "Run" to generate the report.

Edit report query

You can edit the report query and rerun the report to generate a different view of the resource data.

The data generated by a report is displayed in the Data Viewer.

Viewing data

The report data is displayed as a table. The table header displays the names of the requested resource attributes. The requested data for a resource is displayed as rows in the report table.

Export data

The report data can be exported for download by clicking the Download icon. The data is exported as a CSV.

Settings apply to your Eulerio account. You can manage your profile and account details through the Settings page. You can update your user information and password and other details like your billing address on that page.

You can also manage your Eulerio subscription details. You can update your subscription plan or payment method or you can cancel your current subscription. Invoice and billing is accessible from the Settings page.

On the Settings page, you can view and update your user profile.

Edit password

Expand Account Settings to update and save changes to your profile.

Edit Contact Information

Expand the Contact Information Setting to update your information.

Manage your subscription on the Settings page.

Change your plan

You can change your plan at any time to upgrade or downgrade your plan. Changing your plan will affect the resources allocated for your account. If you exceed the resource allocation for your chosen plan, you will be charged for any applicable overage.

Cancel your plan

You can cancel your plan at any time. Cancellation will invalidate your account with Eulerio and any resources allocated for your account will be removed including stored data.

You can view and download your receipts from the Settings page.

Receipts

A list of your receipts are accessible from the Settings page.

Download receipt

Click the Download icon to save a copy of your receipt.

JSON is the primary data format used by Eulerio. JSON is a lightweight data-interchange format that is easy to read and write. It is also universally supported and is the de facto format for interacting with a REST API.

All data payloads in Eulerio are JSON data. Request bodies are passed to the REST API as JSON data and response bodies are returned formatted in JSON.

JSON is also used to describe your resource in Eulerio. The data schema used by Eulerio is based on JSON Schema and it is an easy and familiar way for Eulerio users to configure their resources.

Because schema definition and data payloads are based on JSON, Eulerio is simple to understand and easy to use. The universal nature of JSON makes it a familar paradigm and applications based on it do not require special libraries, drivers, or SDKs to interact with it.

Data in Eulerio are referred to as resources and they are described by properties and defined by values assigned to those properties. A resource describing an artist, for instance, typically contains properties like first name and last name with values for those properties like Ludwig and Beethoven. In order to describe such a resource in Eulerio, a vocabulary is required to describe the relationships between the resource and its properties.

The vocabulary in Eulerio is based on JSON Schema. JSON Schema provides a simple to understand and universal format for describing your data. You can read more about JSON Schema here. Aside from the more exotic aspects of the JSON Schema specification, the majority of features needed for data description using JSON Schema is supported by Eulerio.

To get started using Eulerio, we can consider an application that manages city information. The data we would like to track has the following properties:

• name - the name of the city
• country - the country in which the city is located
• population - the city's population
• sites - notable sites within the city

An example JSON representation for the resource would be:

Describing a resource

In order to store this data in Eulerio, we must first describe the data using JSON Schema. The attributes used to describe the resource are "title" and "description". The "title" attribute contains the name of the resource and "description" provides an optional attribute for summarizing the purpose of the object.

Defining resource properties

Next, we must describe the resource data itself. Each data attribute is a property and properties are defined in JSON schema by associating the property name with meta-data describing it. The "type" meta-data is the key attribute describing the data structure capturing a property's value. The allowable values for "type" are:

• object
• string
• number
• integer
• array
• boolean

Putting it all together

With the resource and properties defined, we can construct the JSON Schema that will describe the city resource in Eulerio. Once the resource has been defined, you can use standard REST APIs exposed by the resource to populate, retrieve, and modify the data for the resource. The complete schema definition for the city resource is:

In the definition of the city resource, we have added a "required" property from JSON Schema to indicate that "name" and "country" must be present for the data to be a valid city resource. The "required" property from JSON Schema takes a list of property names that must be present in the JSON data. We have also added the "type" property to the resource to indicate that it is an object. Finally, the "sites" property demonstrates how to declare a property of type "array" in the schema.

Although the above example is rather simple, it captures the essence of what is required to declare a resource in Eulerio. Most resources can be described using such simple schemas. For more options and further information about JSON Schema, please consult json-schema.org.

JSON is the data format for communicating with Eulerio. It is a standard text-based format for representing objects with properties as key-value pairs. When used in an application, JSON is typically deserialized as an object or an object is serialized as a JSON string. JSON's text representation makes it useful for transmitting data across a network. The MIME type for JSON is "application/json" and this should be set in the Content-Type header when sending JSON data over HTTPS.

Using JSON in Javascript

Methods for handling JSON data in Javascript is provided by the JSON object. The methods are used to convert JSON data to and from a Javascript object. Likewise in other languages, methods are available for handling JSON data.

Converting JSON data to a Javascript object:

Converting a Javascript object to JSON:

Because JSON is a standard text-based format, editing JSON is quite simple. You can use any text editor or online tool to create JSON data. When working with Eulerio, you will use JSON to define your resource schema. Some things to note when creating JSON:

• JSON is a string containing properties as key-value pairs.
• Properties and string values in JSON are always surrounded with double quotes.
• Other valid properties like numbers and booleans are not quoted.
• JSON format is strict. Misplaced commas or colons or unclosed quotes will cause the JSON to be invalid.
• Most available editing tools for JSON have pretty printing capabilities to make JSON easier to read.

There are tools available online that will validate your JSON. These tools usually provide a summary of formatting errors that cause the JSON to be invalid. A populate and free tool for validating JSON is provided by JSONLint.

Resources in Eulerio are accessed through RESTful services. REST is a common paradigm that creates interoperability between different systems. It consists of resources that are accessed through common operations. The data is typically exchanged between systems using a common format such as JSON.

Eulerio supports GET, POST, PUT, and DELETE HTTP methods to access and modify resources. You configure which methods are allowed for each individual resource. This allowance permits granular control of your data.

A REST request is made up of four things:

• resource endpoint
• HTTP method
• headers
• data or request body

The resource endpoint is the url to which you submit your request. In Eulerio, this url for a resource of type "customer" would be:

where "myapi" is your url prefix and customer is the resource you are accessing.

The HTTP method you use will depend on how you are accessing the resource:

• GET - retrieves resource data
• POST - creates a new instance of the resource
• PUT - updates a resource
• DELETE - deletes instances of the resource

Headers that you send along with your request are:

• Authorization - authentication header
• Content-Type - describes the request body format
• Accept - informs the server which response MIME format is accepted by the client

The data or request body contains the resource instance data formatted in JSON.

Curl Example

An example using curl for retrieving customer instances is:

For creating a resource instance:

Javascript Example

The same example in Javascript for retrieving customer resource data:

And for creating a resource instance:

Resource requests to the REST APIs will return HTTP responses. The response will contain headers that provide detailed context of the response and a JSON response body. In particular, the response headers will contain a status code that indicates whether the response has succeeded or failed. The status codes returned are:

• 2xx - the request has been successfully handled
• 3xx - the request is being redirected to another url
• 4xx - there is a problem with the client request
• 5xx - a server error has been encountered

Successful request

A successful request will return a corresponding JSON response body encapsulating the data requested. For instance, a successful GET request for the customer resource will return a collection of customer data. A successful POST request will return the newly created customer resource record.

A customer record returned from a GET request might look like:

Failed Response

A resource endpoint may return a failed response if there are problems with the request or if the server encountered an error trying to process the request. In either case, the returned response will contain an error status code and a JSON response body with an explanation for the error.

When issuing a REST request in your application, you should handle any errors returned from the server. In addition to the status code returned in the response header, the JSON response body returns the details of the errors raised when the server attempted to handle the request.

Example responses for failed requests: