Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add README.md text to help others host index meta-databases #18

Merged
merged 7 commits into from
Dec 21, 2020
Merged
52 changes: 52 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,55 @@ The repository is organized this way:

Presently, only the `v1` version of the formats exist.
Hence, to update the list of providers, file a pull-request against the repository to edit `/src/links/v1/providers.json`.

## Fork this repository to set up an index meta-database for your own databases

- Click on the Fork button in GitHub and follow the instructions.

- Edit `/src/info/v1/info.json` with your information:

- Make sure to update the URL in `available_api_versions` to point at your hosting location.

- Edit `/src/info/v1/info.json` to point out your OPTiMaDe databases:
rartino marked this conversation as resolved.
Show resolved Hide resolved

- Put all your databases on the form:
```
{
"type": "child",
"id": "example_main",
"attributes": {
"name": "Example name",
"description": "Example database containing example entries",
"base_url": "https://www.example.com/optimade",
"homepage": "https://www.example.com"
}
}
```

- Include also the following segment:
```
{
"type": "parent",
"id": "optimade_index",
"attributes": {
"name": "OPTiMaDe providers",
"description": "OPTiMaDe index meta-database of known providers",
"base_url": "https://providers.optimade.org",
"homepage": "https://www.optimade.org"
}
}
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is new!
I like it - but it defeats our idea of "supporting" only two levels (as we write in the spec here) - whatever support means in this context.
I thought the way to include the providers, was simply to include them with the type provider, again, as is indicated in the spec here.
However! I am all for not replicating too much, i.e., having the same providers spread out over all the different implementations. And having the option to direct the client to a continuously updated list of providers seems to be a good one to me.

My only issue with this then, is actually how we should present this link to the list of providers. While this may be one way, it is a bit misinformative - since the list of providers is not a parent of the index meta-database, but rather it's on the same level (in some sense).
Another option would be to introduce a fourth type, like the plural of provider, i.e., "providers" or a combined type of "provider_list".
Another option would be to introduce a type that refers to implementation on the same "level", like "sibling" (to follow on with the child and parent nomenclature), but that feels a bit mis-informative as well, I feel.

So in the end, I am open to ideas, and it may even end up with what you have here. I would just like to raise the discussion to make sure it all makes sense with the rest of the spec (or adapt the spec accordingly).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh... I had somehow gotten the idea that this was how it was supposed to work so that an unbroken tree was presented to the client, which could be traversed both up and down. But you are right that the present specification certainly do not mandate this setup. In particular, the fact that providers are linked out with provider-type objects instead of child already breaks this symmetry.

So, for now I should just remove this segment. But I like your version with a provider_list link.

Copy link
Contributor Author

@rartino rartino Feb 20, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, maybe my confusion ties into Materials-Consortia/OPTIMADE#217 a bit. Should these link objects really have these kinds of different types, or would it be better to change them to be links-type and put the relationship as an attribute field?


- Edit `README.md` to say who you are and what databases you provide.

- Configure your hosting provider to use your forked repository.
The repository presently contains configuration files for Netlify, which you can set up as follows:

- Deploy using the Netlify *Continuous Deployment: GitHub App* option, and give it access to your forked repository with the following settings:

- Build commmand: `jekyll build`
- Publish directory: `_site/`
CasperWA marked this conversation as resolved.
Show resolved Hide resolved

- You are also recommended to set something sane for your subdomain in *Domain settings*, or even setup your own custom domain.
rartino marked this conversation as resolved.
Show resolved Hide resolved

- If you are a provider of OPTiMaDe databases and you have set up the index meta-database to point at them, please post a pull-request against [https://github.com/Materials-Consortia/providers](https://github.com/Materials-Consortia/providers) to add the URL for your index meta-database to the central OPTiMaDe providers list.