jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-irtf-t2trg-rest-iot

Commentary: To be aligned with the dynlink draft
Methods for configuring server push and notification conditions with
CoAP are provided by the CoRE Dynamic Resource Linking specification
I-D.ietf-core-dynlink.
Draft: draft-irtf-t2trg-rest-iot

Commentary: The two terms as presented at IETF 104 RG session
In particular in IoT domain, protocols above transport layer that
are used to transfer data objects and provide semantics for
operations on the data.
Re-usable part of the application layer used to transfer the
application specific data items using a standard set of methods
that can fulfill application-specific operations.
Draft: draft-irtf-t2trg-rest-iot

Commentary: Add to methods section
The CoAP-specific FETCH method RFC8132 requests a representation of a
resource parameterized by a representation enclosed in the request.
The fundamental difference between the GET and FETCH methods is that
the request parameters are included as the payload of a FETCH
request, while in a GET request they're typically part of the query
string of the request URI.
The FETCH method is safe and idempotent.
The PATCH method RFC5789 RFC8132 requests that a set of changes
described in the request entity be applied to the target resource.
The PATCH method is not safe nor idempotent.
The CoAP-specific iPATCH method is a variant of the PATCH method that
is not safe, but is idempotent.
Draft: draft-irtf-t2trg-rest-iot

Commentary: See requirements in Breadth of review comments to be
This document gives guidance for designing Internet of Things (IoT)
systems that follow the principles of the Representational State
Transfer (REST) architectural style.
This document gives guidance for designing Internet of Things (IoT)
systems that follow the principles of the Representational State
Transfer (REST) architectural style.  This document is a product of
the IRTF Thing-to-Thing Research Group (T2TRG).
Draft: draft-irtf-t2trg-rest-iot

Commentary: Tweak a bit the message of this : non - resource identifiers are not really part of the REST style , but a system usually needs them and the IETF has good means with URIs , which include URNs , and can be used for such non - resource identifiers ( e.g. , for physical asset , device , etc . ) . 
 We the terms to the terminology , but should explain a bit more at the end of the URI sections . 
 Solved in
Some schemes are for URIs with main purpose as identifiers and hence
are not dereferencable, e.g., the "urn" scheme can be used to
construct unique names in registered namespaces.  In particular the
"urn:dev" I-D.ietf-core-dev-urn details multiple ways for generating
and representing endpoint identifiers of IoT devices.
Draft: draft-irtf-t2trg-rest-iot

Commentary: ( this one is still WiP )
The components of a RESTful system are assigned one or both of two
roles: client or server.  Note that the terms "client" and "server"
refer only to the roles that the nodes assume for a particular
message exchange.  The same node might act as a client in some
communications and a server in others.  Classic user agents (e.g.,
Web browsers) are always in the client role and have the initiative
to issue requests.  Origin servers always have the server role and
govern over the resources they host.
The components of a RESTful system are assigned one or both of two
roles: client or server.  Note that the terms "client" and "server"
refer only to the roles that the nodes assume for a particular
message exchange.  The same node might act as a client in some
communications and a server in others.  Classic user agents (e.g.,
Web browsers) are always in the client role and have the initiative
to issue requests.  Origin servers always have the server role and
govern over the resources they host.  Simple IoT devices, such as
sensors and actuators, are commonly acting as servers and exposing
their physical world interaction capabilities (e.g., temperature
measurement or door lock control capability) as resources.  Typical
IoT system client can be a cloud service that retrieves data from the
sensors and commands the actuators based on the sensor information.
Alternatively an IoT data storage system could work as a server where
IoT sensor devices send data, in client role.
This improves scalability and reliability, since servers or worker
threads can be replicated.  It also improves visibility because
message traces contain all the information to understand the logged
interactions.
Furthermore, the Stateless constraint enables caching.
This improves scalability and reliability, since servers or worker
threads can be replicated.  It also improves visibility because
message traces contain all the information to understand the logged
interactions.  Furthermore, the Stateless constraint enables caching.
The scaling properties of REST become particularly important in
massive IoT scenarios where thousands or millions of IoT devices may
attempt to interact with a system at the same time.
Draft: draft-irtf-t2trg-rest-iot

Commentary: I just gave this advice and it might be a good rule of thumb : Assuming human - readable representation formats ( i.e. , text - based not binary ) and a client supporting the URI scheme used , a good rule of thumb for a good hypermedia - driven design is the following : A developer should only need an entry point URI to drive the application . All further information how to navigate through the application ( links ) and how to construct more complex requests ( forms ) are published by the server(s ) . There must be no need for additional , out - of - band information ( e.g. , API specification ) . For machines , a well - chosen set of information needs to be shared a priori to agree on machine - understandable semantics . ( Agreeing on the exact semantics of terms for relation types and data elements will of course also help the developer . ) 
 Yes , except that text - based does n't mean human - readable ( as exemplified by JSON -- in reality you need a formatting tool to look at any instances that are n't entirely trivial ) . More important is that the format is self - describing ( and the tool you need to look at that not too obscure ) . 
 Yes , yes , all this is already in the assumptions to get a concise rule of thumb :) Next iteration : Assuming self - describing representation formats ( i.e. , human - readable with carefully chosen terms or processible by a formatting tool ) and a client supporting the URI scheme used , a good rule of thumb for a good hypermedia - driven design is the following : A developer should only need an entry point URI to drive the application . All further information how to navigate through the application ( links ) and how to construct more complex requests ( forms ) are published by the server(s ) . There must be no need for additional , out - of - band information ( e.g. , API specification ) . For machines , a well - chosen set of information needs to be shared a priori to agree on machine - understandable semantics . ( Agreeing on the exact semantics of terms for relation types and data elements will of course also help the developer . ) 
 At least one little update :) Looks good . There 's just a small problem : Nobody is doing it .
Assuming self-describing representation formats (i.e., human-readable
with carefully chosen terms or processible by a formatting tool) and
a client supporting the URI scheme used, a good rule of thumb for a
good hypermedia-driven design is the following: A developer should
only need an entry point URI to drive the application.  All further
information how to navigate through the application (links) and how
to construct more complex requests (forms) are published by the
server(s).  There must be no need for additional, out-of-band
information (e.g., API specification).
For machines, a well-chosen set of information needs to be shared a
priori to agree on machine-understandable semantics.  Agreeing on the
exact semantics of terms for relation types and data elements will of
course also help the developer.
Draft: draft-keranen-t2trg-rest-iot

Commentary: Simple editorial clarifications and typo fixes ; no real content changes
to the server in the form of new representations - rather then
calling a service and modifying the state on the server side.
to the server in the form of new representations - rather than
calling a service and modifying the state on the server side.
instances.  For the IoT systems, it lowers the memory requirements
for server implementations, which is particularly important for
constrained servers (e.g., sensor nodes) and servers serving large
amount of clients (e.g., Resource Directory).
instances.  For IoT systems, this constraint lowers the memory
requirements for server implementations, which is particularly
important for constrained servers (e.g., sensor nodes) and servers
serving large amount of clients (e.g., Resource Directory).
Draft: draft-keranen-t2trg-rest-iot

Commentary: The term " function " might imply idempotence and/or freedom from side effects , depending on who you ask . RPC uses the term " procedure " in order to be more general . 
 would you suggest s / function / procedure / g ? 
 Changed to " procedure "
To modify resource state, clients usually GET a representation from
the server, process it locally, and transfer the resulting state back
to the server with a PUT.  Sometimes, however, the state can only be
modified on the server side, for instance, because representations
would be too large to transfer or part of the required information
shall not be accessible to clients.
In this case, resource state is modified by calling a function.  This
is usually modeled with a POST request, as it leaves the behavior
semantics completely to the server.
To modify resource state, clients usually use GET to retrieve a
representation from the server, modify that locally, and transfer the
resulting state back to the server with a PUT (see sec-uniform-
interface).  Sometimes, however, the state can only be modified on
the server side, for instance, because representations would be too
large to transfer or part of the required information shall not be
accessible to clients.  In this case, resource state is modified by
calling a procedure (or "function").  This is usually modeled with a
POST request, as this method leaves the behavior semantics completely
to the server.  Procedure calls can be divided into two different
classes based on how long they are expected to execute: "instantly"
returning and long-running.
When the procedure can return within the expected response time of
the system, the result can be directly returned in the response.  The
result can either be actual content or just a confirmation that the
call was successful.  In either case, the response does not contain a
representation of the resource, but a so-called action result.
Action results can still have hypermedia controls to provide the
possible transitions in the application state machine.
When the procedure takes longer than the expected response time of
the system, or even longer than the response timeout, it is a good
pattern to create a new resource to track the "task" execution.  The
server would respond instantly with a "Created" status (HTTP code 201
or CoAP 2.01) and indicate the location of the task resource in the
corresponding header field (or CoAP option) or as a link in the
action result.  The created resource can be used to monitor the
progress, to potentially modify queued tasks or cancel tasks, and to
eventually retrieve the result.
Monitoring information would be modeled as state of the task
resource, and hence be retrievable as representation.  The result -
when available - can be embedded in the representation or given as
link to another sub-resource.  Modifying tasks can be modeled with
forms that either update sub-resources via PUT or do a partial write
using PATCH or POST.  Canceling a task would be modeled with a form
that uses DELETE to remove the task resource.
Draft: draft-keranen-t2trg-rest-iot

Commentary: cc 
 +1
Evolvability, Decoupling (server and client from different vendors),
Extensibility at runtime.
The advantage of this approach is increased evolvability and
extensibility.  This is important in scenarios where servers exhibit
a range of feature variations, where it's expensive to keep evolving
client knowledge and server knowledge in sync all the time, or where
there are many different client and server implementations.
Hypermedia controls serve as indicators in capability negotiation.
In particular, they describe available resources and possible
operations on these resources using links and forms, respectively.
Knowledge that needs to be shared a priori among all participants of
a REST system.
A client needs to have knowledge of a couple of things for successful
interaction with a server.  This includes what resources are
available, what representations of resource states are available,
what each representation describes, how to retrieve a representation,
what state changing operations on a resource are possible, how to
perform these operations, and so on.
Some part of this knowledge, such as how to retrieve the
representation of a resource state, is typically hard-coded in the
client software.  For other parts, a choice can often be made between
hard-coding the knowledge or acquiring it on-demand.  The key to
success in either case is the use in-band information for identifying
the knowledge that is required.  This enables the client to verify
that is has all required knowledge and to acquire missing knowledge
on-demand.
variable names that identify the semantics of variables in
templated links,
optionally, well-known locations.
Explain how it works during runtime: server knows application and
offers possible choices to client, client chooses by following links
or submitting forms.
form field names that identify the semantics of form fields in
forms.
The knowledge about these identifiers as well as matching
implementations have to be shared a priori in a RESTful system.
A client begins interacting with an application through a GET request
on an entry point URI.  The entry point URI is the only URI a client
is expected to know before interacting with an application.  From
there, the client is expected to make all requests by following links
and submitting forms that are provided in previous responses.  The
entry point IRI can be obtained, for example, by manual configuration
or some discovery process (e.g., DNS-SD RFC6763 or Resource Directory
I-D.ietf-core-resource-directory).
Draft: draft-keranen-t2trg-rest-iot

Commentary: Very good input , thanks  !
A component embedded in a representation that describes a future
request, such as a link or a form.  By performing the request, the
client can change resource state and/or application state.
A component embedded in a representation that identifies a
resource for future hypermedia interactions, such as a link or a
form.  If the client engages in an interaction with the identified
resource, the result may be a change resource state and/or
application state.
A set of rules for encoding information in a sequence of bytes.
In the Web, the most prevalent representation format is HTML.
Other common formats include plain text (in UTF-8 or another
encoding) and formats based on JSON RFC7159 or XML.  With IoT
systems, often compact formats based on JSON, CBOR RFC7049, and
EXI W3C.REC-exi-20110310 are used.
A sequence of bytes, plus representation metadata, that captures
the current or intended state of a resource and that can be
transferred between clients and servers (possibly via one or more
intermediaries).
A set of rules for serializing resource state.  On the Web, the
most prevalent representation format is HTML.  Other common
formats include plain text and formats based on JSON RFC7159, XML,
or RDF.  Within IoT systems, often compact formats based on JSON,
CBOR RFC7049, and EXI W3C.REC-exi-20110310 are used.
A serialization that represents the current or intended state of a
resource and that can be transferred between clients and servers.
REST requires representations to be self-describing, meaning that
there must be metadata that allows peers to understand which
representation format is used.  Depending on the protocol needs
and capabilities, there can be additional metadata that is
transmitted along with the representation.
A mapping of a resource to a set of values that may change over
time.
A model of a resource's possible states that is represented in a
supported representation type, typically a media type.  Resources
can change state because of REST interactions with them, or they
can change state for reasons outside of the REST model.
Draft: draft-keranen-t2trg-rest-iot

Commentary: Removed " path is hierarchical query not " comment . Added note about query component order being unspecified . 
 This addresses issue 
 Fixed in PR
within the scope of the URI's scheme and naming authority.  The path
is hierarchical; the query is non-hierarchical.  The fragment allows
to refer to some portion of the resource, such as a section in an
HTML document.
within the scope of the URI's scheme and naming authority.  The
fragment allows to refer to some portion of the resource, such as a
section in an HTML document.
The query parameters can be used to parametrize the resource.  For
example, a GET request may use query parameters to request the server
to send only certain kind data of the resource (i.e., filtering the
response).  Query parameters in PUT and POST requests do not have
such established semantics and are not commonly used.
The query parameters can be used to parametrize the resource.  For
example, a GET request may use query parameters to request the server
to send only certain kind data of the resource (i.e., filtering the
response).  Query parameters in PUT and POST requests do not have
such established semantics and are not commonly used.  Whether the
order of the query parameters matters in URIs is unspecified and they
can be re-ordered e.g., by proxies.  Therefore applications should
not rely on their order; see Section 3.3 of RFC6943 for more details.