Skip to content

Commit

Permalink
Update mentions of action in readme (closes #230)
Browse files Browse the repository at this point in the history
  • Loading branch information
ml-evs committed Mar 16, 2020
1 parent acdbdf9 commit 432a53e
Showing 1 changed file with 2 additions and 74 deletions.
76 changes: 2 additions & 74 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The aim of OPTiMaDe is to develop a common API, compliant with the [JSON API 1.0
This is to enable interoperability among databases that contain calculated properties of existing and hypothetical materials.

This repository contains a library of tools for implementing and consuming [OPTiMaDe](https://www.optimade.org) APIs using Python.
It also contains a server validator tool, which may be called from the shell or used as a GitHub Action.
It also contains a server validator tool, which may be called from the shell or used as a GitHub Action from [optimade-validator-action](https://github.com/Materials-Consortia/optimade-validator-action).

_Disclaimer_: While the package supports `elasticsearch-dsl` v6 & v7 and `django` v2 & v3, all tests are performed with the latest supported version.
If you experience any issues with the older versions, you are most welcome to contribute to the repository (see below under Contributing).
Expand All @@ -27,82 +27,10 @@ Installation instructions, for both the index meta-database, and for the main AP

Contribution guidelines and tips can be found in [CONTRIBUTING.md](CONTRIBUTING.md).

## GitHub Action - OPTiMaDe validator

This action runs `optimade_validator` from this repository on a running server.

### Example usage

To run `optimade_validator` for an index meta-database at `http://gh_actions_host:5001/v0` do the following:
Within the same job, first, start a server, e.g., using the `docker-compose.yml` setup from this repository, and then add the step

```yml
uses: Materials-Consortia/optimade-python-tools@master
with:
port: 5001
path: /v0
index: yes
```

To run `optimade_validator` for a regular OPTiMaDe _deployed_ implementation, testing all possible versioned base URLs:

- `https://example.org:443/optimade/example/v0`
- `https://example.org:443/optimade/example/v0.10`
- `https://example.org:443/optimade/example/v0.10.1`

```yml
uses: Materials-Consortia/optimade-python-tools@master
with:
protocol: https
domain: example.org
port: 443
path: /optimade/example
all versioned paths: True
```

### Inputs

#### `protocol`

**Optional** Protocol for the OPTiMaDe URL.
**Default**: `http`

#### `domain`

**Optional** Domain for the OPTiMaDe URL (defaults to the GitHub Actions runner host).
**Default**: `gh_actions_host`

#### `port`

**Optional** Port for the OPTiMaDe URL.
**Default**: `5000`

#### `path`

**Optional** Path for the OPTiMaDe (versioned) base URL - MUST start with `/`
_Note_: If `all versioned paths` is `true`, this MUST be un-versioned, e.g., `/optimade` or `/`, otherwise it MUST be versioned, e.g., the default value.
**Default**: `/v0`

#### `all versioned paths`

**Optional** Whether to test all possible versioned base URLs:

- /vMAJOR
- /vMAJOR.MINOR
- /vMAJOR.MINOR.PATCH

If this is `'true'`, the input `'path'` MUST exempt the version part (e.g., `'/optimade'` instead of `'/optimade/v0'`).
If this is `'false'`, the input `'path'` MUST include the version part (e.g., `'/optimade/v0'` instead of `'/optimade'`).
**Default**: `false`

#### `index`

**Optional** Whether or not this is an index meta-database.
**Default**: `false`

## Links

- [OPTiMaDe Specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst), the human-readable specification that this library is based on.
- [optimade-validator-action](https://github.com/Materials-Consortia/optimade-validator-action), a GitHub action that can be used to validate implementations from a URL.
- [OpenAPI](https://github.com/OAI/OpenAPI-Specification), the machine-readable format used to specify the OPTiMaDe API in [`openapi.json`](openapi.json).
- [Interactive documentation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/openapi.json) generated from [`openapi.json`](openapi.json) (see also [interactive JSON editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/openapi.json)).
- [pydantic](https://pydantic-docs.helpmanual.io/), the library used for generating the OpenAPI schema from [Python models](optimade/models).
Expand Down

0 comments on commit 432a53e

Please sign in to comment.