Documentation

Getting Started

asencis, where permitted to do so, provides open access to the searching, querying, filtering, downloading and exploring of datasets. Datasets can be uploaded and published to asencis, with these exact same features limited to only a smaller, select number of authorised users. Although we are comitted to the open data directive, we understand the need for datasets to be understood by a smaller number of co-collaboartors prior to their public publish, for a number of reasons. However, the vast majority of datasets on asencis will ultimately be open.

Datasets represent the dataset record we hold, as well as the accompanying DatasetDOIRecord, DatasetFileRecord/(s) and DatasetMetaRecord (related to the registration of the dataset with the persistent DOI with the International DOI Foundation (IDF) ). The relationships are set up such that every Dataset will have an extended reverse OneToOne relationship with a DatasetDOIRecord and a DatasetMetaRecord. That means, for every Dataset created with asencis, there will also be an accompanying DatasetDOIRecord and DatasetMetaRecord. There is also a reverse ForeignKey relationshop between the Dataset model and the DatasetFileRecord model, meaning that for every Dataset, there can be none, one or many associated file records*.

Domains and Branches represent scientific disciplines within asencis. Domains provide a relationship link between an individual Dataset and a particular scientific domain. For example, linking "the Chandra X-ray Source Catalog" dataset to the scientific domain of "Astrophysics". A further reverse ForeignKey relationship, abstracted away from the API, provides a link between the Domain and Branch. Branches include Astronomy, Biology, Chemistry, Economics, Engineering, Mathematics, Medicine, Physics, Psychology and Sociology. You have to provide Domain/s when you're creating your Dataset, however, you do not need to provide Branch/es.

Datasets can be searched for by keyword text lookup, as well as by scientific domain and branch.

The Web Interface

The Web Interface is built using Single-Page Application (SPA) archicture, with user-friendly UI.UX and accessibility standards caked in. Not only do we feel that data should be open to everyone, it also should be accessabile for everyone. It needs to be intuitive to use, and follow all modern web standards and practises, as well as being free from errors. We do have error logging with Bugsnag and Sentry across all of our platforms and systems, however if you find any errors that persist for a number of hours please do not hesitate to contact us at bugs@asencis.com.

asencis has the potential to store and retrieve datasets from over 200 scientific domains. This provides you with the ability to discover datasets within your discipline, or related disciplines.

Domains can be searched for in the web interface using a standard client-side typeahead approach, and are entirely case insensitive - that is to say a search for "Astrophysics" or "astrophysics" or even "AsTrOphYsiCs" will return the same result/(s).

Let's start with an example Domain search:

The GraphQL & RESTful APIs

The asencis API comes in three "flavours": the web interface, the RESTful API, and the GraphQL API.

The REST API, as the name suggests, is built upon RESTful principles, meaning the API has predictable resource-oriented URLs, enforces acceptable throttling limits and accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, permission based access and standard HTTP verbs.

Responses are also standardised, and will return results in either JSON or paginated JSON (in maximum page sizes of 30), and follows the latest JSONAPI specification returning a content-type of application/vnd.api+json. With asencis, the retrieving, querying, and browsing functions do not require authentication and are openly available to anyone. However, the creation, updating, and destruction of resources within the system can only be done by either the object owner, in the case of datasets, their respective meta records, and file entities, or system administrators, in the case of domains and measurements *OR* by ensuring that the request user object has the correct permissions for the requested resource (i.e., is the resource owner).

The RESTful API exposes Datasets (and their related Meta, DOI (Digital Object Identifier) and File models), Domains and Measurements.

Authentication for the API is available in two flavours: JSON Web Tokens (JWT) and OAuth2. JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. In essence, JWT allows asencis to determine that your authorised to use the system by providing your username and password, at which point we can begin to ascertain resource permissions for various restricted resources. OAuth2 authentication to asencis will enable applications to obtain limited access to institutional accounts over HTTP by delegating user authentication to the service that hosts the institution's account, and authorizing third-party applications to access that account.

As mentioned, to ensure stability of the system, rate limiting, or request throttling, is enforced for API endpoints. As with permissions, multiple simultaneous throttle rates are applied to the API. asencis applies a more restrictive throttle for unauthenticated requests, and a less restrictive throttle for authenticated requests. Anonymous requests are limited to a maximum of 100/hour (giving a potential of 2400 per day), and authenticated requests of 100000 per day.

The GraphQL API is built upon the principles of the Graph querying language, meaning that all resource queries are routed to one URL, usually /graphql, without a versioning history, whilst providing a complete and understandable description of the data of the API. GraphQL APIs allow for powerful querying and resource matching functionality: retrieving many interlinked resources in a single request whilst asking only for what you need. Responses are also standardised, and will return results in GZip content-encoded (compressed) JSON and follows the latest JSONAPI specification returning a content-type of application/vnd.api+json.

The GraphQL API is an alternative to the RESTful API. However, it currently only supports queries, but not mutations (i.e., create or update actions, e.g. registering a new dataset), so they are optimially used in tandem.