Resource Management in Eulerio

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.

Setting Url Prefix

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.

Image showing how to set a url prefix in Eulerio

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.

Creating Resources

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.

Image demonstrating how to create an Eulerio resource.

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.

Image showing how to set resource values.

Modifying 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.

Image showing how to edit a resource.

Saving modifications

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

Deleting Resources

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.

Image showing how to delete a resource.

Confirm delete

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

Describing Resources

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:

{"firstName":"Joe","lastName":"Smith","age":50}

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:

Image showing an example of a resource schema.

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:

{
  "type":"object",
  "properties":{
    "myStringProperty":{
      "type":"string"
    },
    "myNumberProperty":{
      "type":"number"
    }
  }
}

Sample JSON object data:

{"myStringProperty":"value","myNumberProperty":12.34}

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:

{"myStringProperty":"This is string data"}

number

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

Example number JSON data:

{"myNumberProperty":4.225}

integer

The integer type is used to declare whole numbers.

Example JSON:

{"myIntegerProperty":201}

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:

{"temperatures":[10.0, 16.3, 18.34, 16.2]}

is described by the following schema:

{
  "type":"array",
  "items":{
    "type":"number"
  }
}

boolean

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

Sample JSON:

{"myBooleanProperty":true}

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:

{
  "dob":{
    "type":"string",
    "format":"date-time"
  }
}

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

{"dob":"1904-06-16T00:00:00Z"}

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.

Image showing an example of using unique element.

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.

{
  "errors": [ "Uniqueness Error. Record already Exists for: {'email': 'jack@kerouaccompany.com'}" ],
  "status": 409
}

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.

Image showing an example validation error.

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.

  • $ref
  • oneOf
  • anyof
  • allOf
  • examples
  • const
  • Security

    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.

    Encrypted Communications

    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.

    curl https://eulerio.com/api/myurlprefix/myresource/ -H "Accept: application/json" -H "Authorization: Bearer myaccesskey"

    Access Keys

    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.

    Image showing how to generate a client key.

    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.

    Image demonstrating copying a key

    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.

    Image demonstrating deleting a client access key

    HTTPS Request Examples

    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

    curl https://eulerio.com/api/myurlprefix/myresource/ -H "Accept: application/json" -H "Authorization: Bearer myaccesskey"

    POST request

    curl -X POST https://eulerio.com/api/myurlprefix/myresource/ -H "Content-Type: application/json" -H "Authorization: Bearer myaccesskey" -d "{\"my_attribute\":\"my_attribute_value\"}"

    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.

    curl -X PUT https://eulerio.com/api/myurlprefix/myresource/myresourceid/ -H "Content-Type: application/json" -H "Authorization: Bearer myaccesskey" -d "{\"my_attribute\":\"my_attribute_value\"}"

    DELETE request

    curl -X DELETE https://eulerio.com/api/myurlprefix/myresource/ -H "Content-Type: application/json" -H "Authorization: Bearer myaccesskey" -d "[\"resource_id\"]"

    Monitoring Resource Usage

    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.

    Usage Monitoring

    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.

    Image showing histogram of requests per resource.

    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.

    Image showing pie chart of storage usage

    Activity

    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.

    Image showing histogram of number of requests per resource

    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.

    Table listing user agents making requests.

    Most Active Resources

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

    Table listing most requested resources

    Request History

    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.

    Image showing scatter plot of request history

    Resource Access

    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.

    Accessing Resources

    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.

    resource_url = "https://eulerio.com/api/my_url_prefix/my_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".

    "Accept" : "application/json"
    "Content-Type" : "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>.

    "Authorization" : "Bearer my_client_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.

    [
      {"id":"writer1","firstName":"James","lastName":"Joyce"},
      {"id":"writer2","firstName":"William","lastName":"Faulkner"},
      {"id":"writer3","firstName":"Jack","lastName":"Kerouac"}
    ]

    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.

    resource_url_with_paging = "https://eulerio.com/api/my_url_prefix/my_resource_name/?page=2&limit=50"

    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:

    {"firstName":"Jane","lastName":"Austen"}

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

    [{"firstName":"Jane","LastName":"Austen"},{"firstName":"Leo","lastName":"Tolstoy"}]

    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.

    put_url = "https://eulerio.com/api/my_url_prefix/writer/writer1/
    put_json_body = {"lastName":"Baldwin"}

    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.

    ["writer2","writer3"]

    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.

    https://eulerio.com/api/my_url_prefix/writer/?firstName[eq]=Jane

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

    https://eulerio.com/api/my_url_prefix/writer/?firstName[ne]=Jane

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

    https://eulerio.com/api/my_url_prefix/writer/?age[gt]=40

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

    https://eulerio.com/api/my_url_prefix/writer/?age[gte]=40

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

    https://eulerio.com/api/my_url_prefix/writer/?age[lt]=75

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

    https://eulerio.com/api/my_url_prefix/writer/?age[lte]=75

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

    https://eulerio.com/api/my_url_prefix/writer/?firstName[in]=Jane,James

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

    https://eulerio.com/api/my_url_prefix/writer/?firstName[not-in]=Jack,William

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

    https://eulerio.com/api/my_url_prefix/writer/?firstName[startwith]=Ja

    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.

    https://eulerio.com/api/my_url_prefix/writer/?age[gt]=23&age[lt]=40
    https://eulerio.com/api/my_url_prefix/writer/?age[eq]=23&firstName[eq]=David

    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

    https://eulerio.com/api/my_url_prefix/writer/?age[eq]=23&sortby[asc]=firtName

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

    https://eulerio.com/api/my_url_prefix/writer/?age[eq]=23&sortby[desc]=firtName

    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:

    https://eulerio.com/api/my_url_prefix/writer/writer2/

    will return:

    {"id":"writer2","firstName":"William","lastName":"Faulkner"}

    REST API responses

    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,

    [
      {"id":"writer1","firstName":"James","lastName":"Joyce"},
      {"id":"writer2","firstName":"William","lastName":"Faulkner"},
      {"id":"writer3","firstName":"Jack","lastName":"Kerouac"}
    ]

    or

    {"id":"writer2","firstName":"William","lastName":"Faulkner"}

    Error Codes

    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.

    {"status":403,"errors":"Invalid Token"}

    Generating Reports

    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.

    Creating Reports

    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.

    Image showing how to create a report

    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.

    Image showing how to save a report

    Managing Reports

    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.

    Image showing how to edit a report.

    Delete a report

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

    Image showing how to delete reports.

    Running Reports

    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.

    Image showing how to generate a report.

    Edit report query

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

    Image showing how to edit report query.

    Data Viewer

    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.

    Image showing data viewer.

    Export data

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

    Image showing how to export data

    Managing Settings

    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.

    Managing user profile

    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.

    Image shows how to update profile.

    Edit Contact Information

    Expand the Contact Information Setting to update your information.

    Image shows how to update contact information.

    Manage Subscription

    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.

    Image showing how to change subscription plan

    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.

    Image showing how to cancel subscription plan

    Managing Billing

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

    Receipts

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

    Image showing link to view receipts

    Download receipt

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

    Image showing download of receipt

    Working with JSON

    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.

    JSON Schema

    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:

    {
      "name":"New York",
      "country":"United States",
      "population":19450000,
      "sites":["Empire State Building","Chrysler Building","Times Square"]
    }

    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.

    "title":"City"
    "description":"Compact summary about a city"

    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:

    {
      "title":"City",
      "description":"Compact summary about a city",
      "type":"object",
      "properties":{
        "name":{
          "type":"string"
        },
        "country":{
          "type":"string"
        },
        "population":{
          "type":"integer"
        },
        "sites":{
          "type":"array",
          "items":{
            "type":"string"
          }
        }
      },
      "required":["name","country"]
    }

    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.

    Response Handling

    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:

    jsonData = "{\"key\":\"value\"}";
    object = JSON.parse(jsonData);

    Converting a Javascript object to JSON:

    object = {"key":"value"};
    jsonData = JSON.stringify(object);

    Editing 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.

    Working with REST

    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.

    Creating REST Requests

    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:

    "https://eulerio.com/api/myapi/customer/"

    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:

    curl https://eulerio.com/api/myapi/customer/ -H "Accept: application/json" -H "Authorization: Bearer myaccesskey"

    For creating a resource instance:

    curl -X POST https://eulerio.com/api/myapi/customer/ -H "Content-Type: application/json" -H "Authorization: Bearer myaccesskey" -d "{\"firstName\":\"Joe\",\"lastName\":\"Smith\"}"

    Javascript Example

    The same example in Javascript for retrieving customer resource data:

    fetch('https://eulerio.com/api/myapi/customer/', {
      headers: {
        'Authorization': 'Bearer myaccesskey'
      }
    })
    .then(response => response.json())
    .then(data => console.log(data));

    And for creating a resource instance:

    const data = {firstName: 'Joe', lastName: 'Smith};
    fetch('https://eulerio.com/api/myapi/customer/', {
      method: 'POST',
      body: JSON.stringify(data),
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer myaccesskey'
      }
    })
    .then(response => response.json())
    .then(data => console.log(data));

    Handling REST Response

    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:

    {
      "firstName": "Joe",
      "lastName": "Smith",
      "email": "joesmith@commonjoes.com",
      "phone": "+12125551212"
    }

    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:

    {"status": 400, "errors": "The resource already exists"}
    {"status": 403, "errors": "Invalid Token"}