SIF Infrastructure Specification 3.3: Version Indication & Negotiation www.A4L.org Version 3.3, May 2019 SIF Infrastructure Specification 3.3: Version Indication & Negotiation Version 3.3, May 2019 Preface ...................................................................................................................................... 4 Disclaimer ................................................................................................................................. 4 Permission and Copyright ....................................................................................................... 5 Document Conventions ........................................................................................................... 5 Terms and Abbreviations .......................................................................................................... 5 Notations ..................................................................................................................................... 6 1. Context ............................................................................................................................... 7 2. Problem Statement ........................................................................................................... 8 3. Method ................................................................................................................................ 9 3.1 Schema Identification ........................................................................................................ 9 3.2 Schema Declarations ....................................................................................................... 11 3.2.1 Content-Profile ................................................................................................................ 12 3.2.1.1 HTTP Status Codes ................................................................................................ 13 3.2.2 Accept-Profile .................................................................................................................. 14 3.2.2.1 HTTP Status Codes ................................................................................................ 15 3.2.2.2 Schema Preference ............................................................................................... 15 3.2.2.3 Schema Precedence ............................................................................................. 15 3.2.2.4 Schema Default ....................................................................................................... 16 3.2.2.5 Using Accept-Profile with Accept .................................................................... 16 3.2.3 Link ..................................................................................................................................... 17 3.2.4 Warning: 214 - "Transformation Applied" ............................................................... 18 3.3 SIF Schema Discovery ...................................................................................................... 19 3.4 Assumptions..................................................................................................................... 20 4. Results .............................................................................................................................. 21 4.1 Discovering Supported Schemas ................................................................................... 21 4.2 Get Single and Multiple Objects ..................................................................................... 23 4.3 Create Single Objects ...................................................................................................... 25 4.4 Update Single Objects ..................................................................................................... 26 4.5 Delete Single Objects ...................................................................................................... 26 Copyright © Access 4 Learning Page 2 of 31 SIF Infrastructure Specification 3.3: Version Indication & Negotiation Version 3.3, May 2019 4.6 Create/Update Multiple Objects .................................................................................... 26 4.7 Delete Multiple Objects ................................................................................................... 27 5. Caveats ............................................................................................................................. 28 5.1 SIF Standards ................................................................................................................... 28 5.2 HTTP Standards ............................................................................................................... 28 6. References ........................................................................................................................ 30 Copyright © Access 4 Learning Page 3 of 31 SIF Infrastructure Specification 3.3: Version Indication & Negotiation Version 3.3, May 2019 Preface This document, SIF Infrastructure Specification 3.3: Version Indication & Negotiation, is an addendum to the main volumes of the SIF Infrastructure Specification. It describes features that are experimental because they may represent areas that are rapidly evolving or rely on external specifications that are still in their draft state. Experimental features of SIF are not in scope for SIF compliance and certification processes. It is thus not compulsory for a product adopting SIF to incorporate these features in its implementation. This document is our attempt to adopt two draft technical specifications by W3C and IETF as listed below. They are currently (May 2019) undergoing many changes. • W3C’s content negotiation by profile: https://w3c.github.io/dxwg/conneg-by-ap/ • IETF’s negotiating profiles in HTTP: https://profilenegotiation.github.io/I-D-Accept-- Schema/I-D-accept-schema When experimental features of SIF gain enough attention and maturity, they will be considered for inclusion in the main part of SIF Infrastructure Specification. SIF adopters and standard governance bodies are welcome to evaluate the experimental features and provide feedback to A4L for future improvements. Disclaimer The information, software, products, and services included in the SIF Implementation Specification may include inaccuracies or typographical errors. Changes are periodically added to the information herein. The SIF Association may make improvements and/or changes in this document at any time without notification. Information contained in this document should not be relied upon for personal, medical, legal, or financial decisions. Appropriate professionals should be consulted for advice tailored to specific situations. THE SIF ASSOCIATION, ITS PARTICIPANT(S), AND THIRD PARTY CONTENT PROVIDERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY, RELIABILITY, TIMELINESS, AND ACCURACY OF THE INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS CONTAINED IN THIS DOCUMENT FOR ANY PURPOSE. ALL SUCH INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE SIF ASSOCIATION AND/OR ITS PARTICIPANT(S) HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND Copyright © Access 4 Learning Page 4 of 31 SIF Infrastructure Specification 3.3: Version Indication & Negotiation Version 3.3, May 2019 RELATED GRAPHICS, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. IN NO EVENT SHALL THE SIF ASSOCIATION, ITS PARTICIPANT(S), OR THIRD PARTY CONTENT PROVIDERS BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, SPECIAL, CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, DATA, OR PROFITS, ARISING OUT OF OR IN ANY WAY CONNECTED WITH THE USE OR PERFORMANCE OF THIS DOCUMENT, WITH THE DELAY OR INABILITY TO USE THE DOCUMENT, THE PROVISION OF OR FAILURE TO PROVIDE SERVICES, OR FOR ANY INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS OBTAINED THROUGH THIS DOCUMENT OR OTHERWISE ARISING OUT OF THE USE OF THIS DOCUMENT, WHETHER BASED ON CONTRACT, TORT, STRICT LIABILITY, OR OTHERWISE, EVEN IF THE SIF ASSOCIATION, ITS PARTICIPANT(S), OR THIRD PARTY CONTENT PROVIDERS HAVE BEEN ADVISED OF THE POSSIBILITY OF DAMAGES. IF YOU ARE DISSATISFIED WITH ANY PORTION OF THIS DOCUMENT OR WITH ANY OF THESE TERMS OF USE, YOUR SOLE AND EXCLUSIVE REMEDY IS TO DISCONTINUE USING THIS DOCUMENT. Permission and Copyright Copyright © Access 4 Learning. All Rights Reserved. Document Conventions Terms and Abbreviations Term / Description Abbreviation A4L Access 4 Learning. HTTP Hypertext Transfer Protocol. JSON JavaScript Object Notation. http://json.org/ Copyright © Access 4 Learning Page 5 of 31 SIF Infrastructure Specification 3.3: Version Indication & Negotiation Version 3.3, May 2019 Term / Description Abbreviation REST Representational state transfer, an architectural style of properties and constraints applied to components, connectors and data elements in architecture. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm RESTful Web Web services that follow REST. For simplicity in this document, RESTful Web services services is restricted to those that are HTTP-based. SIF Systems Interoperability Framework. SIF Broker A broker that mediate the interactions between SIF consumers