Date: Thu, 28 Mar 2024 04:38:08 -0500 (CDT) Message-ID: <676521141.28920.1711618688641@PUBEDFIPRDWEB5.public.local> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_28919_51752252.1711618688636" ------=_Part_28919_51752252.1711618688636 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Ed-Fi Request for Comment: 1
Product: Ed-Fi Data Standard v2.1
Affects: Ed-Fi API Design & Implementation Guidelines (and Ed-Fi ODS /=
API)
Obsoletes: --
Obsoleted By: --
Status: Active Proposal for Release=
span>
Geoff McElhanon, Educuity
Ed-Fi Alliance
June 7, 2016
The current (v2.1) REST API Design & Implementation Guidelines cover partial= updates through the HTTP PATCH verb. Partial updates are a way of updating= only select fields on an existing entity, as opposed to sending a complete= representation. The current guidelines recommend a partial object approach= , whereby only those properties requiring update are sent. The proposal aut= hor suggests that the currently recommended approach is ambiguous, and= that a set of established standards (IETF RFC 6902) propo= ses an unambiguous JSON solution suitable for use in Ed-Fi implementations.=
A na=C3=AFve implementation of PATCH might accept a request body whose s= tructure matches exactly that of the target resource, but may only contain = a subset of the properties. The server would then process the properties th= at are present, while leaving those not included as unmodified. While this = is definitely simplistic, there are subtle problems with the semantics of t= his approach.
In strongly-typed languages such as C# and Java, JSON serializers typica= lly have global settings for null and default value handling. For example, = the JSON.NET serializer provides the option to include or ignore null value= s on strongly-typed models being serialized. If the include option is used,= then all nullable properties will be included in the JSON output with expl= icit null values. However, if the ignore option is used, then all propertie= s that have null values will be excluded from the output.
For PUT, where the semantics call for a full replacement of the entire t= arget resource there are no issues introduced for server-side processing. H= owever, using such a non-standard approach for a PATCH implementation using= the resource=E2=80=99s standard representation would create ambiguity. The= process of serializing the message body would not afford the client the ab= ility to explicitly express the intent of the changes. The serialized body = will either include or ignore all null value when serializing the request. = This makes it impossible for the client to express that a particular proper= ty=E2=80=99s null value should be set to null by the server, while another = property=E2=80=99s null value should be ignored because it is not part of t= he intended PATCH operation. Depending on the serializer=E2=80=99s configur= ation, the server would process the resulting request differently.
Proposed in 2010, RFC 5789 for =E2=80=9CPATCH Method = for HTTP=E2=80=9D provides details and guidance for PATCH implementations. = The standard is very clearly written such that a PATCH request consists of = a =E2=80=9Cset of changes represented in a format called a =E2=80=98patch d= ocument=E2=80=99 identified by a media type.=E2=80=9D As opposed to a PUT r= equest (which is a wholesale replacement of an existing resource), the PATC= H request=E2=80=99s =E2=80=9Cenclosed entity contains a set of instructions= describing how a resource currently residing on the origin server should b= e modified to produce a new version.=E2=80=9D
RFC 5789 also indicates that PATCH introduces the potential for collisio= ns that could leave the resource in a =E2=80=9Ccorrupt=E2=80=9D state. To g= uard against this possibility, PATCH implementations on the Ed-Fi REST API = should require ETag checks (as described elsewhere in this document) to ens= ure that a resource isn=E2=80=99t being modified in a way that is unexpecte= d for its current state.
While RFC 5789 doesn=E2=80=99t define a specific patch format, a JSON-ba= sed definition is provided by RFC 6902 for =E2=80=9CJavaSc= ript Object Notation (JSON) Patch=E2=80=9D. Using a request content type of= =E2=80=9Capplication/json-patch+json=E2=80=9D it describes the patch forma= t in terms of operations performed against parts of a JSON document. = Each change to be applied to the target resource must specify an operation = (e.g., add, remove, replace, move, copy, or test), and must identify where = in the document to apply the change using a JSON-Pointer value (as defined = by RFC 6901).
The following listing (from RFC 6902) depicts a PATCH request using this= approach:
PATCH /my= /data HTTP/1.1 Host: example.org Content-Length: 326 Content-Type: application/json-patch+json If-Match: "abc123" =20 [ { "op": "test", "path": "/a/b/c", "value": "foo" }, { "op": "remove", "path": "/a/b/c" }, { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }, { "op": "replace", "path": "/a/b/c", "value": 42 }, { "op": "move", "from": "/a/b/c", "path": "/a/b/d" }, { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" } ]
In summary, an implementation of PATCH for an Ed-Fi REST API should adhe= re to the following proposed Internet Engineering Task Force (IETF) standar= ds:
Suggest the HTTP Verbs section, PATCH item (v2.0 p14) be changed to= read as follows:
PATCH. An HTTP PATCH per= forms a partial update on an existing individual resource using a specializ= ed patch format outlined in RFC 6902. For a partial update, the client subm= its a set of instructions that are processed by the server to apply changes= to the target resource. The entire patch will be applied, or none of it wi= ll. The new representation of the entire resource is returned in the respon= se body with an updated ETag header. The PATCH verb may be support= ed for non-read-only Resources.
Suggest the documentation include references to the relevant IETF RFC ma= terial and an example similar to the example provided in the Detail section= above.