IDS REST

Linked Data Platform (LDP) is the W3C recommended architecture to allow read/write interactions on distributed data using Semantic Web technologies. It combines the well-established identification methods of Web resources (HTTP URIs/URLs) and vocabularies from RDF with the access concepts from Linked Data (data retrieval using HTTP GET, Content-Negotiation). This document presents a binding of IDS interactions to the LDP Recommendation in order to merge the advantages of both approaches: LDP allows the dynamic interaction with unknown entities while the IDS defines patterns to ensure a sovereign and controlled data ecosystem.

The merged approach in this specification presents a union of both LDP and IDS concepts, called IDS-REST. As such, the resulting binding limits the interaction opportunities of the original LDP Recommendation regarding the requirements of the IDS specifications and vice versa. The benefits of the combined approach lie in (a) the simplification of IDS interactions using the LDP best practices, while (b) the trustworthiness of the IDS ecosystem is introduced into LDP-conform applications.

Terminology and Roles

Term	Explanation	Example
LDP Client	User Agent behaving according to the LDP Recommendation
HTTP Client / Client	The network socket sending HTTP requests and receiving response messages. Usually tightly connected with the User-Agent.	Web Browser, cURL
HTTP Server / Server	The network socket receiving HTTP requests and sending response messages. Usually tightly connected with the Origin Server.	One Origin Server could have several server sockets, for instance, one for HTTP, one for MQTT, and one for WebSockets. As all supply the same resources, none of them can be the origin server. The resources are maintained by the Origin Server but their interactions happen through the respective protocol-dependent servers.
User Agent	Software artifact acting on behalf of a user or another component.	Web Browser, HTTP client socket
Connector Operator / Operator	Legal entity controlling and maintaining a specific IDS Connector.
LDP Server	HTTP Server acting as the origin server for an LDP Client.	Marmotta Reference Server, SOLID Server, GAIAboX
resource	Generic data entity, identifiable through an URI
IDS Connector	Gateway providing and requesting data according to IDS specifications.	IDS Metadata Broker, Trusted Connector
Origin server	Entity containing the original data ("the truth") as defined by REST	IDS Connector, HTTP Server
LDP Resource	A Web-based resource which is conform to the LDP specification.
LDP Container	A Web-based resource which conforms to the LDP specification and can host further resources as children.
IDS Resource	A resource which is also an instance of the class ids:Resource.
ids:
ldp:

Table 1: Relevant terms and their roles.

Resources of Interest

The LDP defines a special type of resources that are exposed by servers: Containers. Containers are defined as Resources that can contain further Resources or Containers. This creates a tree-like structure which can be explored following hypermedia links. Therefore, user agents are able to discover the data content of a LDP server on-the-fly and without any external information.

On the other side, an IDS Connector and the IDS Resources it provides must follow the scheme of the IDS Information Model. The rich semantics and the thereby imposed implications of the different IDS classes are crucial for any IDS conform interaction. The thereby imposed complex operation semantics however is explicitly not regarded by the LDP Recommendation. That implies the following consequences for a LDP binding in the IDS:

• IDS Connectors are the single Origin Server of an IDS Resource.

• The root container must be an instance of the class ids:Connector or one of its subclasses.

• Offered data is collected in an instance of ids:Catalog, which at the same time appears as an ldp:Container.

• ids:/ldp:Resources inside an ids:Catalog can have further child resources.

• Allowed operations, for instance the creation or deletion of a resource, depend on the location of the target resource in the data tree. Certain resources (instance of ids:Connector at the root level and its catalog) can be deleted or updated only by the Connector Operator.

Motivation

At the time of writing this document, the IDS interactions follow a message-driven pattern. The IDS attributes are partitioned and encoded in defined message types according to the Multipart format. With this specification all IDS interactions are supported. Therefore, the obvious questions are: Why is it necessary to define yet another interaction pattern? This contradiction is crucial to answer as every additional layer of specifications, requirements and standardization increases the onboarding efforts of developers and thereby hinders the adoption of the IDS in general.

It has been shown that the proposed Multipart and message-driven communication is significantly complex to implement for a huge proportion of developers. The success of the IDS however is directly dependent on a vivid and motivated developer community. Therefore, the IDS must provide the patterns that developers are familiar with instead of insisting on rarely used technologies. In addition, the tool support for Multipart messages is rather limited, while there is a massive trend towards REST APIs on the Web but also in any kind of distributed architectures.

First and foremost, REST APIs restrict the number of assumptions a consuming application needs to make about a remote endpoint. The protocol, possible states, state transformations, exchange sequences, error behavior, and so on need to be understood by all parties. REST is already a well-known and commonly accepted paradigm providing recommendations (not necessarily answers!) to a lot of these topics. Reusing them simplifies the life of the developers, increases the maintainability, and last but not least presents the condensed lessons learned of a huge community.

Apart from these design advantages, the tool support for REST APIs is significantly better - especially in terms of open source projects - than for any other communication pattern.

Following this argumentation, the IDS community agreed that a REST binding is required. Whether it - at some point - might even replace the currently used interaction patterns is not in the scope of this document. The hereby presented binding is intended as an coequal binding with the same relevance and commitment as the other bindings.

Operations and Interactions

An instance of an IDS Message, as defined in the IDS Information Model, encodes i.a. the intended command, content, target, expected response. For example, an ArtifactRequestMessage contains its operational semantics ('return an IDS Artifact'), the target resource, expected response (ArtifactResponseMessage), data format (Multipart) etc. This implies that both the sender and the receiver of the message need to share all these assumptions and deeply understand the IDS requirements and side-effects. Obviously, this is especially hard for people joining the IDS community but also for experienced IDS developers.

The REST paradigm on the other hand separates the command semantics from the content and deeply integrates the communication pattern with HTTP methods. This reduces the necessary assumptions but also restricts the expressiveness of the interaction. In addition, REST interactions are stateless. In terms of the IDS communication and data exchange, this means that neither the server nor the client is expected to remember previous interactions or how a current request fits into an ongoing sequence of requests. As a consequence, all requests must be complete so that they provide all necessary information for their correct execution. Hence, User-Agents interact with IDS Connectors only through the URI pointing at the target resource, the eight HTTP methods (GET, PUT, POST, DELETE, HEAD, OPTIONS, PATCH, TRACE), the HTTP Headers and the optional request body. Therefore, an explicit mapping of the defined message types to the resource- and state-based view of REST is required. The following sections outline this mapping in detail.

IDS Message Mapping

Notification Message Name	IDS-REST Mapping	Description
RequestMessage	GET {Resource URL} Identification URI must be identical with the URL the resource is hosted at.	Client-generated message initiating a communication, motivated by a certain reason and with an answer expected. May be used for messages, which are not covered by the core IDS messages.
ResultMessage	HTTP Response	Result messages are intended to annotate the results of a query command.
ResponseMessage	HTTP Response	Response messages hold information about the reaction of a recipient to a formerly sent command or event. They must be correlated to this message .
		May be used for messages, which are not covered by the core IDS messages.
ResourceUpdateMessage	PUT {Resource URL} Resource instance as serialized RDF in the request body	Message indicating an update of a specific resource
ResourceUnavailableMessage	DELETE {Resource URL}	Message indicating that a specific resource is unavailable
ResourceAvailableMessage	PUT {URL of the catalog on the server} Resource instance as serialized RDF in the request body
RequestInProcessMessage	HTTP Response with status code 1xx	Notification that a request has been accepted and is being processed.
RejectionMessage	HTTP Response with status code 4xx or 5xx	Rejection messages are specialized response messages that notify the sender of a message that processing of this message has failed.
QueryMessage	GET {Connector Root or Query Endpoint} Percent-encoded query in Query Parameters	Query message intended to be consumed by specific components.
	POST {Connector Root or Query Endpoint} Query in the request body.
ParticipantUpdateMessage	PUT {Participant URL} Participant instance as serialized RDF in the request body
ParticipantUnavailableMessage	DELETE {Participant URL}	Event notifying the recipient(s) that a participant will be unavailable and never be available again
ParticipantResponseMessage	HTTP Response	Message that follows up a ParticipantRequestMessage and contains the Participant's information in the payload section.
ParticipantRequestMessage	GET {Participant URL}	Message asking for retrieving the specified Participants information as the payload of an ParticipantResponse message
ParticipantCertificateUnavailableMessage	POST {Connector Inbox URL} message content as serialized RDF in the request body	Indicates that a (previously certified) Participant is no more certified. This could happen, for instance, if the Certification Body revokes a granted certificate or if the certificate has just expired.
ParticipantCertificateGrantedMessage	POST {Connector Inbox URL} message content as serialized RDF in the request body	Whenever a Participant has been successfully certified by the Certification Body, the Identity Provider can use this message to notify Infrastructure Components
ParticipantAvailableMessage	POST {Connector Offers URL at the ParIS Catalog} Participant instance as serialized RDF in the request body	Event notifying the recipient(s) about the availability of a new participant.
	PUT {URL of the Participant at the server} Participant instance as serialized RDF in the request body
OperationResultMessage	HTTP Response	Message indicating that the result of a former InvokeOperation message is available. May transfer the result data in its associated payload section
NotificationMessage	POST {Connector Inbox URL} message content as serialized RDF in the request body	Notification messages are informative and no response is expected by the sender. May be used for scenarios, which are not covered by the core IDS messages.

Request Message Name	IDS-REST Mapping	Description
MessageProcessedNotificationMessage	HTTP Response with status code 2xx	Notification that a message has been successfully processed (i.e., not ignored or rejected).
LogMessage	POST {Connector Inbox URL} message content as serialized RDF in the request body	Log Message which can be used to transfer logs, e.g., to the clearing house.
InvokeOperationMessage	POST {ids:Interactive Endpoint URL}[?{query parameter}]	Message requesting the recipient to invoke a specific operation.
DescriptionResponseMessage	HTTP Response	Message containing the metadata, which a Connector previously requested via the ids:DescriptionRequestMessage, in its payload.
DescriptionRequestMessage	GET {resource URL} Header: "Accept: application/ld+json" or any other well-known RDF MIME type	Message requesting metadata. If no URI is supplied via the ids:requestedElement field, this messages is treated like a self-description request and the recipient should return its self-description via an ids:DescriptionResponseMessage. However, if a URI is supplied, the Connector should either return metadata about the requested element via an ids:DescriptionResponseMessage, or send an ids:RejectionMessage, e.g. because the element was not found
ContractSupplementMessage	undefined	Message containing supplemental information to access resources of a contract.
ContractResponseMessage	undefined	Message containing a response to a contract request (of a data consumer) in form of a counter-proposal of a contract in the associated payload (which is an instance of ContractOffcer).
ContractRequestMessage	POST {ids:Interactive Endpoint URL} or {Target resource URL}	Message containing a suggested content contract (as offered by the data consumer to the data provider) in the associated payload (which is an instance of ids:ContractRequest).
ContractRejectionMessage	HTTP Response with status code 400	Message indicating rejection of a contract.
ContractOfferMessage	POST {ids:Interactive Endpoint URL} or {Target resource URL}	Message containing a offered content contract (as offered by a data provider to the data consumer) in the associated payload (which is an instance of ContractOffer). In contrast to the ids:ContractResponseMessage, the ids:ContractOfferMessage is not related to a previous contract request.
ContractAgreementMessage	HTTP Response to a ContractOfferMessage or ContractRequestMessage	Message containing a contract with resource access modalities on which two parties have agreed.
ConnectorUpdateMessage	PUT {URL of the connector at the server} Connector instance as serialized RDF in the request body	Event notifying the recipient(s) about a connector's configuration change. The payload of the message must contain the updated connector's self-description.
ConnectorUnavailableMessage	DELETE {URL of the connector at the server}	Event notifying the recipient(s) that a connector will be unavailable and never be available again.
ConnectorInactiveMessage	DELETE {URL of the connector at the server} Connector instance as serialized RDF in the request body	Message notifying the recipient(s), that a connector will be inactive and most likely be available again in the future.
ConnectorCertificateRevokedMessage	POST {Connector Inbox URL} message content as serialized RDF in the request body	Indicates that a (previously certified) Connector is no more certified. This could happen, for instance, if the Certification Body revokes a granted certificate or if the certificate has just expired.
ConnectorCertificateGrantedMessage	POST {Connector Inbox URL} message content as serialized RDF in the request body	Whenever a Connector has been successfully certified by the Certification Body, the Identity Provider can use this message to notify Infrastructure Components.
ConnectorAvailableMessage	POST {Broker Catalog URL} Connector instance as serialized RDF in the request body	Event notifying the recipient(s) about the availability of a new connector. The payload of the message must contain the new connector's self-description.
	PUT {URL of the connector at the server} Connector instance as serialized RDF in the request body
CommandMessage	POST {ids:Interactive Endpoint URL}[?{query parameter}] A dedicated ids:Endpoint does not behave as a ldp:Container. A POST will not create a new child resource but trigger the distinct service offered by this endpoint.	Command messages are usually sent when a response is expected by the sender. Changes state on the recipient side. Therefore, commands are not 'safe' in the sense of REST.
ArtifactResponseMessage	HTTP Response	Message that follows up a ArtifactRequestMessage and contains the Artifact's data in the payload section.
ArtifactRequestMessage	GET {Artifact/Representation/Resource URL} Header: "Accept: application/octet-stream"	Message asking for retrieving the specified Artifact as the payload of an ArtifactResponse message.
AccessTokenRequestMessage	POST {Authorization Server} Query Parameter: CLIENT_ID, CLIENT_SECRET, GRANT_TYPE, (AUTHORIZATION_)CODE, CALLBACK_URL, SCOPE, STATE	Message requesting an access token. This is intended for point-to-point communication with, e.g., Brokers.
AccessTokenResponseMessage	See [RFC 6749]	Response to an access token request, intended for point-to-point communication.

Table 2: IDS Message Types and their representation in the IDS REST protocol.

Encryption

Currently, TLS encryption of all messages is required in the IDS. Unencrypted requests, for instance plain HTTP, must always be rejected. Furthermore, certificates and keys used for the communication encryption must be valid and signed by a trustworthy CA. A client must not expect a reasonable response for non-encrypted requests, even if the server responds with a redirect to the HTTPS URL.

Identification and Location

Following the IDS Information Model, IDS entities, such as Participants, Connectors, or Resources, are represented by information documents containing a self-description. In addition, each IDS entity has its own unique URI identifier.

IDS components can use this URI to find a document representing the entity. For instance, Connector A (https://example.org/ConnectorA) asks the IDS Metadata Broker for information about a Connector B (https://example.org/ConnectorB). Subsequently, the Broker responds with a document containing a representation of the current state of the Connector B (ConnectorB.jsonld) as far as the Metadata Broker has stored it.

Note that in this example, the Identifier URI of Connector B (https://example.org/ConnectorB) is not necessarily equal to the URL at which it's endpoints (https://companyB.com/ids/connector/data/) are located. Furthermore, Connector A must know the Broker's endpoint URL (https://metadata-broker.org/infrastructure) in advance. Connector A can then lookup the received document representing Connector B (ConnectorB.jsonld), discover the endpoint URL, and send a request to it.

The IDS-REST approach is significantly different. The identifying URI is bound to the location of the entity itself. Therefore, Connector B must not use https://example.org/ConnectorB as its identifier but https://companyB.com/ids/connector/ instead and provide at least a self-description document at this location. This enables Connector A by learning about a Connector B (identified by https://companyB.com/ids/connector/) to directly communicate with it without further lookups on endpoints. The identification URI must always be the same as the root URL under which the entity is hosted. However, this simplification on the client connector-side increases the effort on the server connector-side as the later must always synchronize identities with hosting locations.

Authentication

The IDS transfers and validates identity claims using the Dynamic Attribute Token (DAT). The DAT contains, among other attributes, the signed identity of an IDS Connector.

Each IDS Connector involved in an interaction, both the origin server and the user agent, must verify the respective DAT of the counterpart by the following sequence

1. Compare the signature with the public key of the referenced Dynamic Attribute Provisioning Service (DAPS)

2. Compare the announced public keys with the certificate used for the TLS channel

3. Verify the iat, exp, nbf time stamps.

4. Check if the security claims match their own security specifications.

Protocol

The operation semantics follows the typical REST semantics for CRUD operations. The following items state the usual interpretation of the eight HTTP methods as remote commands.

• GET: Read the target resource

• PUT: Overwrite the target resource state. If it did not exist, create it with the sent state. The desired resource state is in the request body.

• POST: Create a new resource (if the target resource is an LDP Container). The desired resource state is in the request body. Undefined for non-LDP Containers.

• DELETE: Delete the target resource.

• HEAD: Read the meta-information of the target resource.

• OPTIONS: Read the allowed HTTP operations on the target resource.

• PATCH: Attach content to the target resource.

• CONNECT: undefined method for IDS-REST

The IDS REST binding follows this pattern. The following sections explain the generally used parts like headers, body and response structure, the error codes, and maps the IDS Messages to these interaction items.

Request Headers

Header Key	Header Value	Cardinality
ids-authorizationToken	Header to set a Connector-specific authorization token.	optional
ids-contentVersion	The version/revision of the data content in the body.	optional
ids-issuerConnector	Original Connector of the request.	mandatory
ids-modelVersion	Information Model version, against which the Message should be interpreted.	mandatory if the body contains an IDS Entity.
ids-issued	XSD DateTimeStamp (xsd:dateTimeStamp) of issuing the response.	mandatory
ids-senderAgent	Agent who initiated the response	mandatory
ids-recipientAgent	Agent, for which the response is intended.	optional, implicitly defined by the target resource
ids-securityToken	Dynamic Attribute Token (DAT) representing the security-related claims, for instance that the sender supports a certain security profile.	mandatory
ids-transferContract	The contract which is (or will be) the legal basis of the data transfer.	optional
Accept	A comma-separated list of MIME types, which the client wants to accept.	optional
Content-Type	MIME type of the data in the response body.	mandatory if the body is present.
If-Match	The version of the resource the client wants to change. Is used to detect collisions. The client is informed by the server of correct versions through the ETag response header.	mandatory, if the client wants to overwrite a remote resource
Slug	The desired new name of a resource, which the client wants to create.	optional

Table 3: Request headers.

Full list of http-header attributes to use see here.:

Request Body

For every class except an ids:Artifact, the body of the HTTP request must always contain a valid RDF serialization. An ids:Artifact can also contain non-RDF or even binary data. In any case, the serialization of the body must be announced in the corresponding value of the "Content-Type" header. The default serialization in the IDS is JSON-LD (media type: 'application/ld+json'). Systems not able to operate on RDF can also treat the content as plain JSON and parse it like that (media type: 'application/json').

Still, every IDS compliant message exchange must use valid JSON-LD serializations, in particular by using the JSON key "@context" with either a proper local context definition or by linking to an appropriate remote context document. The default context element for the IDS is "@context": "https://w3id.org/idsa/contexts/context.jsonld".

The context key-value pair must always be the first one in any IDS compliant JSON or JSON-LD object.

Access Control

Access control (AC) to a given resource is inspired by the W3C work on the "Web Access Control" (WAC) language. However, the permissions and restrictions that can be expressed by WAC are not sufficient for the IDS scenarios, mainly due to the missing support for Contract Classes. For instance, the context 'time' is not considered by WAC.

In general, an IDS-REST client must add an DAT to its request. Without it, or if the DAT is not valid or contains conflicting statements, for instance issued-at before not-after, the IDS-REST server must directly reject the request. The IDS-REST server must return a 4xx status code and may return an additional indication in the response body. Independent of incorrect DATs, an IDS-REST server may also require custom Access Tokens. The recommended behavior is to use the ids-authorizationToken request header. The tokens can be maintained through well-established standards, like OAuth2, or through proprietary processes. This gives the Providers of Connectors the ability to create own data spaces where only dedicated Participants can access protected resources.

Usage Control

The IDS-REST binding solely targets the interactions and operations at the interface of a Connector to the outside network. Both client (Data Consumer) and server (Data Provider) therefore only focus on Access restrictions for enforcement. The explicit Usage Control tasks happen inside the Data Consumer and are not directly affecting the client-server interaction anymore.

Nevertheless, the IDS-REST binding contains the means to express usage restrictions as instances of Contracts. Contracts are represented as any other Web resource and can retrieved and manipulated accordingly. Their distinct meaning, to outline and control operations on data, is defined by the IDS Information Model and further specifications. The IDS-REST binding is therefore an agnostic layer to pave the way for Usage Control but does not by itself add further specifications.

Response

Every request message must be answered with the according HTTP response message. In case the receiving IDS Connector assumes a misuse, for instance, a denial of service attack, it could also block the requester. In any other case, the response message must contain a reference to the originating message, an HTTP status code, a set of response headers and optional data in the response body.

Response Header

The response headers are the same as the request header.

For the full list of http-header attributes to use, see here.

Header Key	Header Value	Cardinality
ids-modelVersion	Information Model version, against which the Message should be interpreted.	mandatory if the body contains an IDS Entity.
ids-issued	XSD DateTimeStamp (xsd:dateTimeStamp) of issuing the response.	mandatory
ids-senderAgent	Agent who initiated the response	mandatory
ids-recipientAgent	Agent, for which the response is intended.	optional, implicitly defined by the target resource
ids-securityToken	Dynamic Attribute Token (DAT) representing the security-related claims, for instance that the sender supports a certain security profile.	mandatory
ids-transferContract	The contract which is (or will be) the legal basis of the data transfer.	optional
Content-Type	MIME type of the data in the response body.	mandatory if a response body is present.
Accept-Post	A comma-separated list of allowed media types, for instance "text/turtle", "application/ld+json" (for descriptions conforming to the IDS Information Model), or "application/octet-stream" (for binary data or IDS Artifacts).	optional
Link		mandatory if the response body contains a LDP or IDS resource.
ETag	A unique version identifier representing the current state of the requested resource.	mandatory
Allow	The enabled HTTP methods, selection of GET, OPTIONS, HEAD, PUT, PATCH, POST, DELETE, CONNECT	mandatory

Table 4: Response headers.

Status Codes

Although the IDS Information Model contains its own status codes, the commonly known HTTP codes are used as much as possible. The following table lists the available ones:

Code	Meaning	Example
1xx	The origin server has received the request and will continue working on it. The IDS not explicitly specifies the meaning of this group of status codes.
102	Processing. The server needs some time to process the request.
200	Ok. The request is valid. May or may not respond with data.
201	Created. A new resource has been created. The URL of the new resource has to be announced through the "Link" header.
204	No Content. The server has received the request but does not send any content back.
301	Moved Permanently. The target resource will not appear again at this location. Must return the new target URL. The client is assumed to send the request again to the announced URL.
303	See other. The client is assumed to send the request again to the announced URL.
400	Bad Request. The request was not compliant to this specification. The server may or may not indicate the problem.
403	Forbidden. The user agent has no permission to access the target resource. The typical response also for invalid DATs.
404	Not Found. The target resource does not exist.
405	Method Not Allowed. The target method can not treat the request method. Could happen that IDS specifications do not allow the desired operation on the target resource.	Deleting the root resource (ids:Connector) results in a 405 error code.
406	Not Acceptable. The desired content types (see "Accept" header) can not be served.
409	Conflict. The request does not fit to the current state of the target resource or violates specifications. The server may or may not indicate the problem.
410	Gone. The resource exists no longer. Similar to 404 but with more information for the client.
500	Internal Server Error. Something went wrong. The server may or may not indicate the problem or how to solve it.
501	Not (Yet) Implemented. Endpoint might show up later.
503	Service (Temporarily) Unavailable. Try later.

Table 5: Status codes of responses.

Complex Operations and Workflows

Composed workflows or more elaborate interactions that can not be directly mapped to the previously outlined plain HTTP operations have to be managed by the User-Agent and the Origin Server respectively. While each Rest interaction - containing exactly one request/response pair - is exhaustive by definition, typical IDS workflows require more complex communication patterns.

That implies that even though the single interactions are stateless, and therefore only defined by the current state of the target resource and the HTTP message, the Origin Server and the User-Agent must remember the results of previous interactions to some degree. The respective obligations depend on the type of intended operation and is specified through the sub-classes of the IDS Message class. The following table outlines the binding of the Message semantic with the respective REST binding for the IDS:

Interaction Pattern	IDS-REST Request Binding	IDS-REST Response Binding	Consequence
Send a command (ids:CommandMessage)	POST to the operation endpoint. Further parameters or requirements need to be described by the endpoint itself.	102: Command execution takes more time, please wait.	unsafe, not idempotent
		200: Operation successful, response body may contain the command result
		40x: Error in the request, optional explanation in the response body.
Retrieve the description of any IDS instance	GET at the URL of the IDS instance ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target resource representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Retrieve an IDS Contract(ids:DescriptionRequest)	GET at the respective path of the IDS Contract ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target resource representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Retrieve an IDS Artifact (ids:ArtifactRequestMessage)	GET at the respective path of the IDS Artifact ("Accept: application/octet-stream" or any other fitting MIME type value, for instance "text/csv", "image/jpeg" etc.)	200: Body containing the target resource representation	safe, idempotent, memorizing not necessary
Retrieve a description (ids:DescriptionRequest) of an IDS Resource	GET at the respective path of the IDS Resource ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target resource representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Retrieve a description of an IDS Participant (ids:ParticipantRequest-Message)	GET at the respective path of the IDS Contract ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target participant representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Retrieve a description (ids:DescriptionRequest) of an IDS Representation	GET at the respective path of the IDS Representation ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target resource representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Retrieve a description (ids:DescriptionRequest) of an IDS Connector	GET at the root path of the IDS Connector ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target resource representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Retrieve a description (ids:DescriptionRequest) of an IDS Artifact	GET at the respective path of the IDS Artifact ("Accept: application/ld+json" or "Accept: application/json")	200: Body containing the target resource representation;	safe, idempotent, memorizing not necessary
		403 or 406: Optional explanation in the response body.
Response Message	Response messages are directly defined by HTTP Responses. No (asynchronous) interaction sequence is intended by the IDS-REST Binding.
Request an Access Token (ids:AccessTokenRequest-Message)	POST to the Authorization Server as specified by OAuth2: CLIENT_ID, CLIENT_SECRET, GRANT_TYPE, (AUTHORIZATION_)CODE, CALLBACK_URL, SCOPE, STATE; Note: An Access Token is different to the Dynamic Attribute Token that is issued from the IDS DAPS. The Access Token as referenced here is intended for authorization mechanisms on top of the IDS specifications.	200: AccessToken in response body.
		invalid_request	see RFC 6749 - The OAuth 2.0 Authorization Framework
		unauthorized_client
		access_denied
		unsupported_response_type
		invalid_scope
		server_error
		temporarily_unavailable (instead of 503)
Register an IDS Resource at an IDS Metadata Broker	PUT to the offers list of a connector instance.	200: OK	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict
Register an IDS Participant at ParIS	POST to a ParIS Catalog. Slug Header contains the desired instance name, which the server is should use if possible.	201: Resouce Created, must return the "Location: " Header	unsafe, not idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict
Register an IDS Participant at ParIS	PUT to a ParIS Catalog child instance.	200: OK	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict
Register an IDS Connector at an IDS Metadata Broker	POST to an IDS Catalog. Slug Header contains the desired instance name, which the server is should use if possible.	201: Resouce Created, must return the "Location: " Header	unsafe, not idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict
Register an IDS Connector at an IDS Metadata Broker	PUT to an IDS Catalog child instance.	201: Resouce Created, must return the "Location: " Header	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict
Overwrite the state of an IDS Resource at an IDS Metadata Broker	PUT to an IDS Resource URL. The request body must contain the complete new instance state.	200: OK	unsafe, idempotent
	If-Match header must be set accordingly.	400: Bad Request
		406: Not Allowed
		409: Conflict
Overwrite the state of an IDS Participant at a ParIS	PUT to a ParIS Catalog child instance.	200:OK	unsafe, idempotent
	If-Match header must be set accordingly.	400: Bad Request
		406: Not Allowed
		409: Conflict
Overwrite the state of an IDS instance	PUT to a resource URL, which shall be created, for instance an IDS Participants, IDS Artifact, IDS Contract. The request body must contain the complete new instance state.	200:OK	unsafe, idempotent
	If-Match header must be set accordingly.	400: Bad Request
		406: Not Allowed
		409: Conflict
Overwrite the state of an IDS Connector at an IDS Metadata Broker	PUT to a Catalog instance URL. The request body must contain the complete new instance state.	200:OK	unsafe, idempotent
	If-Match header must be set accordingly.	400: Bad Request
		406: Not Allowed
		409: Conflict
ids:ContractRequestMessage	POST to the referenced ContractOffer. If no (suitable) ids:ContractOffer is provided, target resource is the ids:Resource itself. Must contain a valid IDS Contract Request (in JSON-LD, if the server has not signaled other supported content types before).	200: ContractRequest is accepted, ContractAgreement is in the response body.	unsafe, not idempotent, both connectors must store at least the resulting ids:ContractAgreement.
		400: HTTP Request itself is fine but the Contract Request is not accepted. A desired respective Contract Offer may be sent in the response payload.
ids:ContractOfferMessage	POST to the referenced ContractRequest. If no (suitable) ids:ContractRequest is provided, target resource is the ids:Resource itself. Must contain a valid IDS Contract Offer (in JSON-LD, if the server has not signaled other supported content types before).	200: ContractOffer is accepted, ContractAgreement is in the response body.	unsafe, not idempotent, both connectors must store at least the resulting ids:ContractAgreement.
		400: HTTP Request itself is fine but the Contract Request is not accepted. A desired respective Contract Offer may be sent in the response payload.
Execute a remote operation (ids:InvokeOperationMessage)	POST to the operation endpoint. Further parameters or requirements need to be described by the endpoint itself.	102: Operation execution takes more time, please wait.	unsafe, not idempotent
		200: Operation successful, response body may contain the operation result
		40x: Error in the request, optional explanation in the response body.
Execute a complex query (ids:QueryMessage)	POST to the query endpoint. Query is included in the request body. Content-Type Header presents the used query language, for instance "Content-Type: application/sparql-query". The Accept Header outlines the desired response format, for instance "Accept: text/csv".	200: Query successful, response body containing the query result	safe, idempotent
		400: Error in the request or the query, optional explanation in the response body.
Execute a complex query (ids:QueryMessage)	GET to the query endpoint. Query parameters are percent-encoded using the HTTP query parameters 'query', 'default-graph-uri', and 'named-graph-uri'.	200: Query successful, response body containing the query result	safe, idempotent
		400: Error in the request or the query, optional explanation in the response body.
Delete the state of an IDS Participant at a ParIS	DELETE to the URL which represents the Participant in the ParIS Catalog.	200:OK	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
Delete an IDS Resource at an IDS Metadata Broker	DELETE to the URL which represents the Resource in the Broker Catalog.	200:OK	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
Delete an IDS instance	DELETE to a resource URL	200:OK	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
Delete an IDS Connector at an IDS Metadata Broker	DELETE to a the URL which represents the Connector in the Broker Catalog.	200:OK	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
Create an IDS instance	PUT to a resource URL, which shall be created, for instance an IDS Participants, IDS Artifact, IDS Contract. The request body must contain the complete new instance state.	201: Resouce Created	unsafe, idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict
Create an IDS instance	POST to a parent instance, for example, an IDS Connector, IDS Resource, or IDS Catalog. Slug Header contains the desired instance name, which the server is should use if possible. If no request body is provided, the server creates a default instance, which must conform to the IDS Information Model.	201: Resouce Created, must return the "Location: " Header	unsafe, not idempotent
		400: Bad Request
		406: Not Allowed
		409: Conflict

Table 6: Interaction patterns and their mapping in the IDS-REST binding.

A connector conform to IDS REST must, in addition to the general criteria for IDS Connectors, implement the following features:

• It must have a self-description hosted at its root path. Note that the root path is not necessarily the first segment of an URL path but the first dedicated section for the connector. For instance, for https://example.org/ids/connector/some/ids/endpoint/ the root path can start after 'connector/'

• All entities have at least one URL which points to their location on a Connector server.

• All Resources/Representations/Artifacts must be able to handle related Contract interactions sent to them. At least an error message must be returned.

Notifications

Notifications and publish/subscribe or push-based communication are not yet parts of the IDS REST protocol binding. While this functionality may be introduced in the future, the Linked Data Notification may serve as a preliminary reference. See here IDS Linked Data Notification (IDS-LDN)

Identification and Naming of Resources

Even though the structure of the URL of a resource must not necessarily reflect its location on the server, it is recommended to apply this pattern by the Origin Server. For instance, creating a resource called https://bad-example.org/some-resource can be created at an IDS Connector at https://example.org/connector/:

@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix ids:  <https://w3id.org/idsa/core/> .
@prefix ldp:  <http://www.w3.org/ns/ldp#> .

<https://example.org/connector/>
    a ids:BaseConnector, ldp:BaseContainer ;
    ids:catalog [
        a <https://example.org/connector/Catalog> ;
        ids:offers <https://bad-example.org/some-resource> ;
        ldp:contains <https://bad-example.org/some-resource> ;
    ] ;
    ldp:contains <https://example.org/connector/Catalog> ;
    #...
.

However, without further specifications, the Origin Server has the complete naming authority. It could therefore respond instead:

201

Link: https://example.org/connector/Catalog/some-resource

And update its state as:

@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix ids:  <https://w3id.org/idsa/core/> .
@prefix ldp:  <http://www.w3.org/ns/ldp#> .

<https://example.org/connector/>
    a ids:BaseConnector, ldp:BaseContainer ;
    ids:catalog [
          a <https://example.org/connector/Catalog> ;
          ids:offers <https://example.org/connector/Catalog/some-resource> ;
          ldp:contains <https://example.org/connector/Catalog/some-resource> ;
    ] ;
    ldp:contains <https://example.org/connector/Catalog> ;
    #...
.

Therefore, the User Agent must not expect its originally suggested name to be used by the Origin Server. However, the Origin Server should take the User Agent's suggestions into account, and serve them as long as possible. The client can use the "Slug" header to indicate the desired path extension.

Equality of Resources

Despite ids:Contracts, the equality or non-equality of resources can be expected. For instance, the same ids:DataResource can be hosted at several IDS Connectors with no obligation to announce this fact. This is different for Contracts - and especially ids:ContractAgreements - as those imply legal consequences. A Contract published at one place must not have an extended copy at some other place. While the Contract itself can of course be copied, it must always the same URI.

Furthermore, no IDS Connector is allowed to rename, extend, update or shorten an ids:ContractAgreement.

REST API Documentation (non-normative)

• IDSA Swagger API

Community-provided Descriptions

• https://app.swaggerhub.com/apis/jlangkau/IDS-LDP/

• PolicyInformationPoint API Description

Example IDS REST Request (non-normative)

The example below shows a typical Multipart Message, sent with a POST request:

--msgpart
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="header"

{
  "@context" : "https://w3id.org/idsa/contexts/context.jsonld",
  "@type" : "ids:ConnectorAvailableMessage",
  "@id" : "http://industrialdataspace.org/connectorAvailableMessage/34d761cf-5ca4-4a77-a7f4-b14d8f75636a",
  "issued" : "2019-12-02T08:25:08.245Z",
  "modelVersion" : "4.1.0",
  "issuerConnector" : "https://companyA.com/connector/59a68243-dd96-4c8d-88a9-0f0e03e13b1b",
  "securityToken" : {
    "@type" : "ids:DynamicAttributeToken",
    "tokenFormat" : "https://w3id.org/idsa/code/tokenformat/JWT",
    "tokenValue" : "eyJhbGciOiJSUzI1NiIsInR5cCI..."
  }
}


--msgpart
Content-Type: application/json
Content-Disposition: form-data; name="payload"

<Payload: Self-description of the Connector>

This Multipart Message can be transformed to the following REST request:

GET https://www.example.org/server/cpu_3
ids-modelVersion : "4.1.0"
ids-issuerConnector: "https://wall-e.nicos-rd.com/"
ids-securityToken: "eyJ1c2VyIjoiam90dCJ9...42"
ids-issued: "2019-12-02T08:25:08.245Z"
Accept: text/turtle

References and Related Resources

Name	Description	Location
IDS Message Taxonomy	Documentation of the Message Types and their attributes.
Linked Data Platform 1.0	Standard for read/write Linked Data
Web Access Control (WAC) Language	Method and Vocabulary to restrict access to Web Resources
Web Access Control (WAC) specification	WAC specification as used by the Solid project
Learning Linked Data	Introduction to Linked Data
The IDS Communication Guide	IDSA-internal guide how to interact with IDS Messages
ODRL Information Model 2.2	Vocabulary for the expression of Digital Rights
RFC 6749	RFC for OAuth 2
Linked Data Notifications	Specification how to exchange push messages conform to LDP interactions.

Authors

Name	Affiliation	Channel	Account
Sebastian Bader		GitHub
Jörg Langkau		Mail	[e-mail]
		GitHub
		twitter

Contributers

Name	Affiliation	Channel	Account
Stefanie Koslowski		GitHub

Version History

Revision	Date	Author	Change
0.6	17.06.2021		finalizing the renaming from IDS-LDP to IDS-REST
0.5	30.04.2021		addressing the rest of the review comments and reworking the document for the upcoming specification; adding the Request Header Table
0.4	15.01.2021		addressing the review comments
0.3	04.11.2020		Correcting br tags and Table1
0.2	03.11.2020		adjusting tables, and deleting a few copy paste errors
0.1	31.08.2020		Initial file

---