Welcome to OmicronServer’s documentation!

Contents:

• 1. Installation
  • 1.1. Dependencies
    • 1.1.1. Windows Users and Python Packages
  • 1.2. Running the Code
  • 1.3. Running Tests
• 2. A Brief Concepts Summary
  • 2.1. Representational State Transfer (REST)
    • 2.1.1. The Role of an API
    • 2.1.2. Enter REST
    • 2.1.3. HTTP and REST: Why They Go So Well Together
  • 2.2. Git and GitHub
    • 2.2.1. Git: Distributed Version Control
    • 2.2.2. GitHub: A Hub For Git
  • 2.3. Relational Databases and You
• 3. Technologies Used in This Project
  • 3.1. Libraries
    • 3.1.1. Flask
    • 3.1.2. Flask-RESTful
    • 3.1.3. SQLAlchemy
  • 3.2. Git and GitHub
    • 3.2.1. Git: Distributed Version Control
  • 3.3. Travis CI
  • 3.4. Coveralls
  • 3.5. Heroku
  • 3.6. SQLAlchemy
• 4. Web API
  • 4.1. Introduction
  • 4.2. URL Endpoints
• 5. API Reference
  • 5.1. Contents
    • 5.1.1. API Documentation
      • 5.1.1.1. api_server
      • 5.1.1.2. authentication
      • 5.1.1.3. config
      • 5.1.1.4. decorators
      • 5.1.1.5. JSON Schema Parser
    • 5.1.2. Database API
      • 5.1.2.1. Database Models
        • 5.1.2.1.1. Projects
        • 5.1.2.1.2. Users
      • 5.1.2.2. Database Management API
        • 5.1.2.2.1. ContextManagedSession
        • 5.1.2.2.2. Versioning
        • 5.1.2.2.3. Schema
    • 5.1.3. API Views
      • 5.1.3.1. Schema-defined Resource
      • 5.1.3.2. Projects
      • 5.1.3.3. Users
• 6. Tests
  • 6.1. Integration Tests
    • 6.1.1. Test Database Round-Trip
    • 6.1.2. Test Auth
  • 6.2. Unit Tests
    • 6.2.1. Top-Level Modules
      • 6.2.1.1. API Server
      • 6.2.1.2. Auth
      • 6.2.1.3. Config
      • 6.2.1.4. Decorators
      • 6.2.1.5. JSON Schema Parser

Introduction

OmicronServer forms the back end of the Omicron Project, which aims to automate a large part of laboratory processes and record-keeping.

Audience

This document is intended for developers coming from a non-Python background to understand how this software works, and how to contribute additional functionality to the software.

In addition, this document is intended for reading by potential consumers of this API, in order to understand what each HTTP request in this API does.

Readme

Welcome to OmicronServer

OmicronServer is the back end for Omicron Web Services, a project that aims

to automate much of the process engineering and experimentation

Badges

Installation

A stable version of OmicronServer has not yet been released. TravisCI builds are run on all branches and pull requests with every commit, but features may be lacking in these builds. See the issues and project milestones for a timeline of future releases.

$ git clone https://github.com/MichalKononenko/OmicronServer.git

Packages and Dependencies

Dependencies are outlined in requirements.txt. In order to install dependencies, run

pip install -r requirements.txt

TravisCI uses this file to install all its dependencies, and Heroku uses this to identify OmicronServer as a Python project.

Since Travis runs on Linux, it has the advantage of using gcc to compile some of the packages listed here. your machine may not have this luxury, and so you may have to find binaries for the psycopg2 package, in order to connect to PostgreSQL

Supported Versions

This project is currently supported for Python versions

• 2.7
• 3.4
• 3.5

Supported Databases

OmicronServer currently supports PostgreSQL and SQLite.

Running the Program

To run the server, run

$ python run_server.py

from the command line. By default, the server will run on localhost:5000. The address can be specified by setting the IP_ADDRESS and PORT environment variables in your command line.

Environment Variables

The file config.py will adjust its settings depending on the value of several environment variables. These are

• IP_ADDRESS: The IP address at which the server is to be hosted

• PORT: The port number at which the server is to be hosted

• BASE_DIRECTORY: The base directory where run_server.py is kept. By default, this is the current directory of the config.py file

• TOKEN_SECRET_KEY: The secret key used as a salt to generate authentication tokens for the user. Tokens are not stored on

  the back end, but are generated from user data, and the value of TOKEN_SECRET_KEY. If this value is changed, the user’s token will no longer work.

• DATABASE_URL: The URL at which the database sits. This is the database to be used by the server

• DEBUG: If TRUE, then stack traces will be displayed when in the browser if the server throws a 500 error

• STATE: A generic flag for specifying between DEV, CI, and PROD machines. Currently not wired to anything

• LOGFILE: The file to which the log should be written. If this is not

  defined, the application log will be written to `sys.stdout`.

Command Line Parsing

Unfortunately, the values above must be set as environment variables as OmicronServer does not currently support parsing these arguments in the command line

License

This project and all files in this repository are licensed under the GNU General Public License (GPL) version 3. A copy of this license can be found in the LICENSE file

Indices and tables

• Index
• Module Index
• Search Page