Beginning with 2nd June, only the "Single Sign On" option for login to the GitLab web interface will be possible. If you don't have an MPCDF wide second factor so far, please get one at our SelfService (https://selfservice.mpcdf.mpg.de). The GitLab internal second factor will not work.
(and its [fork on GitHub](https://github.com/nomad-coe/nomad){:target="_blank"}).
This project contains all the framework and infrastructure code. It instigates all checks,
builds, and deployments for the public NOMAD service, the NOMAD Oasis, and the `nomad-lab`
Python package. All contributions to NOMAD have to go through this project eventually.
All (Git) projects that NOMAD depends on are either a Git submodule (you find
them all in the `dependencies` directory or its subdirectories) or they are
listed as PyPI packages in the `pyproject.toml` of the main project (or one of its
submodules).
You can also have a look at the [built-in plugins](../../reference/plugins.md) that constitute the majority of these projects. The only other projects are [MatID](https://github.com/nomad-coe/matid){:target="_blank"}, [DOS fingerprints](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-dos-fingerprints){:target="_blank"}, and the [NOMAD Remote Tools Hub](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-remote-tools-hub){:target="_blank"}.
You can also have a look at the [built-in plugins](../../reference/plugins.md) that
constitute the majority of these projects. The only other projects are
@@ -8,14 +8,17 @@ To access the processed data with our client library `nomad-lab` follow
## Different options to use the API
NOMAD offers all its functionality through application
programming interfaces (APIs). More specifically [RESTful HTTP APIs](https://en.wikipedia.org/wiki/Representational_state_transfer){:target="_blank"} that allows you
to use NOMAD as a set of resources (think data) that can be uploaded, accessed, downloaded,
searched for, etc. via [HTTP requests](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol){:target="_blank"}.
You can get an overview on all NOMAD APIs on the [API page]({{ nomad_url() }}../../gui/analyze/apis).
We will focus here on NOMAD's main API (v1). In fact, this API is also used by
the web interface and should provide everything you need.
NOMAD offers all its functionality through application programming interfaces (APIs). More
@@ -222,11 +226,13 @@ The result will look like this:
}
```
You can work with the results in the given JSON (or respective Python dict/list) data already.
If you have [NOMAD's Python library](./pythonlib.md) installed ,
you can take the archive data and use the Python interface.
The [Python interface](../plugins/schema_packages.md#wrap-data-with-python-schema-classes) will help with code-completion (e.g. in notebook environments),
resolve archive references (e.g. from workflow to calculation to system), and allow unit conversion:
You can work with the results in the given JSON (or respective Python dict/list) data
already. If you have [NOMAD's Python library](./pythonlib.md) installed, you can take the
- Raw files, the files as they were uploaded to NOMAD.
- Archive data, all of the extracted data for an entry.
There are also different entities (see also [Datamodel](../../explanation/basics.md)) with different functions in the API:
There are also different entities (see also [Datamodel](../../explanation/basics.md))
with different functions in the API:
- Entries
- Uploads
...
...
@@ -275,17 +283,20 @@ Let's discuss some of the common concepts.
### Response layout
Functions that have a JSON response, will have a common layout. First, the response will contain all keys and values of the request. The request is not repeated verbatim, but
in a normalized form. Abbreviations in search queries might be expanded, default values for optional parameters are added, or additional response specific information
is included. Second, the response will contain the results under the key `data`.
Functions that have a JSON response, will have a common layout. First, the response will
contain all keys and values of the request. The request is not repeated verbatim, but
in a normalized form. Abbreviations in search queries might be expanded, default values
for optional parameters are added, or additional response specific information is
included. Second, the response will contain the results under the key `data`.
### Owner
All functions that allow a query will also allow to specify the `owner`. Depending on
the API function, its default value will be mostly `visible`. Some values are only
available if you are [logged in](#authentication).
All functions that allow a query will also allow to specify the `owner`. Depending on the
API function, its default value will be mostly `visible`. Some values are only available
if you are [logged in](#authentication).
{{ doc_snippet('owner')}}
### Queries
{{ doc_snippet('query') }}
...
...
@@ -293,10 +304,11 @@ available if you are [logged in](#authentication).
### Pagination
When you issue a query, usually not all results can be returned. Instead, an API returns
only one *page*. This behavior is controlled through pagination parameters,
like `page_site`, `page`, `page_offset`, or `page_after_value`.
only one *page*. This behavior is controlled through pagination parameters, like
`page_site`, `page`, `page_offset`, or `page_after_value`.
Let's consider a search for entries as an example.
```py
response=requests.post(
f'{base_url}/entries/query',
...
...
@@ -313,8 +325,9 @@ response = requests.post(
)
```
This will only result in a response with a maximum of 10 entries. The response will contain a
`pagination` object like this:
This will only result in a response with a maximum of 10 entries. The response will
contain a `pagination` object like this:
```json
{
"page_size":10,
...
...
@@ -345,10 +358,11 @@ response = requests.post(
}
)
```
You will get the next 10 results.
Here is a full example that collects the first 100 formulas from entries that match
a certain query by paginating.
Here is a full example that collects the first 100 formulas from entries that match a
certain query by paginating.
```python
--8<--"examples/docs/api/pagination.py"
...
...
@@ -357,7 +371,8 @@ a certain query by paginating.
### Authentication
Most of the API operations do not require any authorization and can be freely used
without a user or credentials. However, to upload, edit, or view your own and potentially unpublished data, the API needs to authenticate you.
without a user or credentials. However, to upload, edit, or view your own and potentially
unpublished data, the API needs to authenticate you.
The NOMAD API uses OAuth and tokens to authenticate users. We provide simple operations
that allow you to acquire an *access token* via username and password:
