baseinfo

AvailableApiVersion

A JSON object containing information about an available API version

Source code in optimade/models/baseinfo.py

class AvailableApiVersion(BaseModel):
    """A JSON object containing information about an available API version"""

    url: AnyHttpUrl = StrictField(
        ...,
        description="A string specifying a versioned base URL that MUST adhere to the rules in section Base URL",
        pattern=r".+/v[0-1](\.[0-9]+)*/?$",
    )

    version: SemanticVersion = StrictField(
        ...,
        description="""A string containing the full version number of the API served at that versioned base URL.
The version number string MUST NOT be prefixed by, e.g., 'v'.
Examples: `1.0.0`, `1.0.0-rc.2`.""",
    )

    @validator("url")
    def url_must_be_versioned_base_url(cls, v):
        """The URL must be a valid versioned Base URL"""
        if not re.match(r".+/v[0-1](\.[0-9]+)*/?$", v):
            raise ValueError(f"url MUST be a versioned base URL. It is: {v}")
        return v

    @root_validator(pre=False, skip_on_failure=True)
    def crosscheck_url_and_version(cls, values):
        """Check that URL version and API version are compatible."""
        url_version = (
            values["url"]
            .split("/")[-2 if values["url"].endswith("/") else -1]
            .replace("v", "")
        )
        # as with version urls, we need to split any release tags or build metadata out of these URLs
        url_version = tuple(
            int(val) for val in url_version.split("-")[0].split("+")[0].split(".")
        )
        api_version = tuple(
            int(val) for val in values["version"].split("-")[0].split("+")[0].split(".")
        )
        if any(a != b for a, b in zip(url_version, api_version)):
            raise ValueError(
                f"API version {api_version} is not compatible with url version {url_version}."
            )
        return values

url: AnyHttpUrl = StrictField(Ellipsis, description='A string specifying a versioned base URL that MUST adhere to the rules in section Base URL', pattern='.+/v[0-1](\\.[0-9]+)*/?$') class-attribute

version: SemanticVersion = StrictField(Ellipsis, description="A string containing the full version number of the API served at that versioned base URL.\nThe version number string MUST NOT be prefixed by, e.g., 'v'.\nExamples: `1.0.0`, `1.0.0-rc.2`.") class-attribute

crosscheck_url_and_version(values)

Check that URL version and API version are compatible.

Source code in optimade/models/baseinfo.py

@root_validator(pre=False, skip_on_failure=True)
def crosscheck_url_and_version(cls, values):
    """Check that URL version and API version are compatible."""
    url_version = (
        values["url"]
        .split("/")[-2 if values["url"].endswith("/") else -1]
        .replace("v", "")
    )
    # as with version urls, we need to split any release tags or build metadata out of these URLs
    url_version = tuple(
        int(val) for val in url_version.split("-")[0].split("+")[0].split(".")
    )
    api_version = tuple(
        int(val) for val in values["version"].split("-")[0].split("+")[0].split(".")
    )
    if any(a != b for a, b in zip(url_version, api_version)):
        raise ValueError(
            f"API version {api_version} is not compatible with url version {url_version}."
        )
    return values

url_must_be_versioned_base_url(v)

The URL must be a valid versioned Base URL

Source code in optimade/models/baseinfo.py

@validator("url")
def url_must_be_versioned_base_url(cls, v):
    """The URL must be a valid versioned Base URL"""
    if not re.match(r".+/v[0-1](\.[0-9]+)*/?$", v):
        raise ValueError(f"url MUST be a versioned base URL. It is: {v}")
    return v

BaseInfoAttributes

Attributes for Base URL Info endpoint

Source code in optimade/models/baseinfo.py

class BaseInfoAttributes(BaseModel):
    """Attributes for Base URL Info endpoint"""

    api_version: SemanticVersion = StrictField(
        ...,
        description="""Presently used full version of the OPTIMADE API.
The version number string MUST NOT be prefixed by, e.g., "v".
Examples: `1.0.0`, `1.0.0-rc.2`.""",
    )
    available_api_versions: List[AvailableApiVersion] = StrictField(
        ...,
        description="A list of dictionaries of available API versions at other base URLs",
    )
    formats: List[str] = StrictField(
        default=["json"], description="List of available output formats."
    )
    available_endpoints: List[str] = StrictField(
        ...,
        description="List of available endpoints (i.e., the string to be appended to the versioned base URL).",
    )
    entry_types_by_format: Dict[str, List[str]] = StrictField(
        ..., description="Available entry endpoints as a function of output formats."
    )
    is_index: Optional[bool] = StrictField(
        default=False,
        description="If true, this is an index meta-database base URL (see section Index Meta-Database). "
        "If this member is not provided, the client MUST assume this is not an index meta-database base URL "
        "(i.e., the default is for `is_index` to be `false`).",
    )

    @validator("entry_types_by_format", check_fields=False)
    def formats_and_endpoints_must_be_valid(cls, v, values):
        for format_, endpoints in v.items():
            if format_ not in values["formats"]:
                raise ValueError(f"'{format_}' must be listed in formats to be valid")
            for endpoint in endpoints:
                if endpoint not in values["available_endpoints"]:
                    raise ValueError(
                        f"'{endpoint}' must be listed in available_endpoints to be valid"
                    )
        return v

api_version: SemanticVersion = StrictField(Ellipsis, description='Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., "v".\nExamples: `1.0.0`, `1.0.0-rc.2`.') class-attribute

available_api_versions: List[AvailableApiVersion] = StrictField(Ellipsis, description='A list of dictionaries of available API versions at other base URLs') class-attribute

available_endpoints: List[str] = StrictField(Ellipsis, description='List of available endpoints (i.e., the string to be appended to the versioned base URL).') class-attribute

entry_types_by_format: Dict[str, List[str]] = StrictField(Ellipsis, description='Available entry endpoints as a function of output formats.') class-attribute

formats: List[str] = StrictField(default=['json'], description='List of available output formats.') class-attribute

is_index: Optional[bool] = StrictField(default=False, description='If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be `false`).') class-attribute

formats_and_endpoints_must_be_valid(v, values)

Source code in optimade/models/baseinfo.py

@validator("entry_types_by_format", check_fields=False)
def formats_and_endpoints_must_be_valid(cls, v, values):
    for format_, endpoints in v.items():
        if format_ not in values["formats"]:
            raise ValueError(f"'{format_}' must be listed in formats to be valid")
        for endpoint in endpoints:
            if endpoint not in values["available_endpoints"]:
                raise ValueError(
                    f"'{endpoint}' must be listed in available_endpoints to be valid"
                )
    return v

BaseInfoResource

Source code in optimade/models/baseinfo.py

class BaseInfoResource(Resource):
    id: str = Field("/", regex="^/$")
    type: str = Field("info", regex="^info$")
    attributes: BaseInfoAttributes = Field(...)

attributes: BaseInfoAttributes = Field(Ellipsis) class-attribute

id: str = Field('/', regex='^/$') class-attribute

type: str = Field('info', regex='^info$') class-attribute