Skip to content

Server Information

Get Server Information

As a ONE Record client, it is helpful to know the capabilities of a ONE Record server and to be able to retrieve this information in a systematic way. Therefore, every ONE Record server MUST provide an endpoint that can be used to retrieve this technical server information. This ServerInformation include details about the ONE Record server's ONE Record capabilities, the data holder (as a link to an Organization using the Organization URI), the supported Logistics Object types (incl. data model versions) and the supported serialization formats.

The ServerInformation is a data class of the ONE Record API ontology. The properties and relationships to other data classes are visualized in the following class diagram.

classDiagram   
    direction LR   

    class Organization{        
    }  

    class ServerInformation{
        + hasDataHolder: Organization                
        + hasServerEndpoint: xsd:anyURI        
        + hasSupportedApiVersion[]: xsd:string [1..*]
        + hasSupportedContentType[]: xsd:string [1..*]        
        + hasSupportedEncoding[]: xsd:string [*]
        + hasSupportedLanguage[]: xsd:string [1..*]
        + hasSupportedOntology[]: xsd:anyURI [1..*]
        + hasSupportedOntologyVersion[]: xsd:anyURI [1..*]
    }        
    ServerInformation "1" --> "1" Organization

Endpoint

 GET {{baseURL}}/

Request

The following HTTP header parameters MUST be present in the request:

Request Header Description Examples
Accept The content type that you want the HTTP response to be formatted in. application/ld+json

Response

One of the following HTTP status codes MUST be present in the response:

Code Description Response body
200 The request to retrieve the ServerInformation has been successful ServerInformation
301   Indicate that the server has moved permanently to a new location No response body
401   Not authenticated or expired token Error
403   Not authorized to perform action Error
404   Resource Not Found Error
405   Method not allowed Error
415   Unsupported content type Error
500   Internal Server Error Error

A successful request MUST return a HTTP/1.1 200 OK status code and the following HTTP headers parameters MUST be present in the response:

Response Header Description Example
Content-Type The content type that is contained with the HTTP body. application/ld+json
Content-Language Describes the language(s) for which the requested resource is intended. en-US
Last-Modified The date and time of the most recent change to the server information. See https://developer.mozilla.org/en-US/docs/Web/ Tue, 21 Feb 2023 07:28:00 GMT

The HTTP body must contain a valid ServerInformation object in the format as specified by the Content-Type in the header.

Security

Any authenticated ONE Record client that is aware of this endpoint should have the capability to request Server Information from the ONE Record server. Therefore, access control should not be applied to this endpoint, and authentication alone should suffice.

Example A1

Request:

GET / HTTP/1.1
Host: 1r.example.com
Content-Type: application/ld+json; version=2.0.0-dev
Accept: application/ld+json; version=2.0.0-dev

Response:

HTTP/1.1 200 OK
Content-Type: application/ld+json; version=2.0.0-dev

{
    "@context": {
        "cargo": "https://onerecord.iata.org/ns/cargo#",
        "api": "https://onerecord.iata.org/ns/api#"
    },
    "@id": "https://1r.example.com/",
    "@type": "api:ServerInformation",
    "api:hasDataHolder": {
        "@type": "cargo:Company",
        "@id": "https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda"
    },
    "api:hasServerEndpoint": "http://1r.example.com",
    "api:hasSupportedApiVersion": [
        "2.0.0-dev"
    ],
    "api:hasSupportedContentType": [
        "application/ld+json"
    ],
    "api:hasSupportedLanguage": [
        "en-US"
    ],    
    "api:hasSupportedOntology": [
        "https://onerecord.iata.org/ns/cargo/3.0.0",
        "https://onerecord.iata.org/ns/api/2.0.0-dev"
    ]
}
(ServerInformation.json)

Example A2

Request:

GET / HTTP/1.1
Host: 1r.example.com
Accept: application/ld+json; version=2.0.0-dev

Response:

HTTP/1.1 301 Moved Permanently
Location: https://1r.example.org/