Help
RSS
API
Feed
Maltego
Contact
Domain > api-guidelines.bsh-cloud.com
×
More information on this domain is in
AlienVault OTX
Is this malicious?
Yes
No
DNS Resolutions
Date
IP Address
2024-05-22
3.162.163.75
(
ClassC
)
2024-12-25
204.246.191.3
(
ClassC
)
Port 80
HTTP/1.1 301 Moved PermanentlyServer: CloudFrontDate: Wed, 25 Dec 2024 19:42:59 GMTContent-Type: text/htmlContent-Length: 167Connection: keep-aliveLocation: https://api-guidelines.bsh-cloud.com/X-Cache: Redirect from cloudfrontVia: 1.1 e90b27f8a13d44c35911b9b6b13e0d9e.cloudfront.net (CloudFront)X-Amz-Cf-Pop: HIO50-C2X-Amz-Cf-Id: YT2gHQIHvEhjEeEfRB_zdaWhKQSWRZ9aRFd_IEBxYqo5yZH_U3_NAw html>head>title>301 Moved Permanently/title>/head>body>center>h1>301 Moved Permanently/h1>/center>hr>center>CloudFront/center>/body>/html>
Port 443
HTTP/1.1 200 OKContent-Type: text/htmlContent-Length: 232031Connection: keep-aliveDate: Wed, 25 Dec 2024 19:43:00 GMTLast-Modified: Wed, 18 Sep 2024 14:35:29 GMTETag: bf70bd4bf7402155c275f793eebd25d0x-amz-server-side-encryption: AES256Accept-Ranges: bytesServer: AmazonS3X-Cache: Miss from cloudfrontVia: 1.1 3396f08538cae17d7cab5e402e844a54.cloudfront.net (CloudFront)X-Amz-Cf-Pop: HIO50-C2X-Amz-Cf-Id: O4T8yL2bBIwCRjq7sMPnTarq7FaYbaBwfEjS9Cm0OohMcPk9Rif1yQ !DOCTYPE html>html langen>head>meta charsetUTF-8>meta http-equivX-UA-Compatible contentIEedge>meta nameviewport contentwidthdevice-width, initial-scale1.0>meta namegenerator contentAsciidoctor 2.0.20>meta namekeywords contentBSH, Guidelines, RESTful, API, Schema>meta namecopyright contentCC-BY-SA 4.0>title>BSH CI API Guidelines/title>style>/*! normalize.css v2.1.2 | MIT License | git.io/normalize *//* HTML5 display definitions *//** Correct `block` display not defined in IE 8/9. */article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }/** Correct `inline-block` display not defined in IE 8/9. */audio, canvas, video { display: inline-block; }/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */audio:not(controls) { display: none; height: 0; }/** Address `hidden` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox 22. */hidden, template { display: none; }script { display: none !important; }/* Base *//** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }/** Remove default margin. */body { margin: 0; }/* Links *//** Remove the gray background color from active links in IE 10. */a { background: transparent; }/** Address `outline` inconsistency between Chrome and other browsers. */a:focus { outline: thin dotted; }/** Improve readability when focused and also mouse hovered in all browsers. */a:active, a:hover { outline: 0; }/* Typography *//** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */h1 { font-size: 2em; margin: 0.67em 0; }/** Address styling not present in IE 8/9, Safari 5, and Chrome. */abbrtitle { border-bottom: 1px dotted; }/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */b, strong { font-weight: bold; }/** Address styling not present in Safari 5 and Chrome. */dfn { font-style: italic; }/** Address differences between Firefox and other browsers. */hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }/** Address styling not present in IE 8/9. */mark { background: #ff0; color: #000; }/** Correct font family set oddly in Safari 5 and Chrome. */code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }/** Improve readability of pre-formatted text in all browsers. */pre { white-space: pre-wrap; }/** Set consistent quote types. */q { quotes: \201C \201D \2018 \2019; }/** Address inconsistent and variable font size in all browsers. */small { font-size: 80%; }/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }sup { top: -0.5em; }sub { bottom: -0.25em; }/* Embedded content *//** Remove border when inside `a` element in IE 8/9. */img { border: 0; }/** Correct overflow displayed oddly in IE 9. */svg:not(:root) { overflow: hidden; }/* Figures *//** Address margin not present in IE 8/9 and Safari 5. */figure { margin: 0; }/* Forms *//** Define consistent border, margin, and padding. */fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people arent caught out if they zero out fieldsets. */legend { border: 0; /* 1 */ padding: 0; /* 2 */ }/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */button, input { line-height: normal; }/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */button, select { text-transform: none; }/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */button, html inputtypebutton, inputtypereset, inputtypesubmit { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }/** Re-set default cursor for disabled elements. */buttondisabled, html inputdisabled { cursor: default; }/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */inputtypecheckbox, inputtyperadio { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */inputtypesearch { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */inputtypesearch::-webkit-search-cancel-button, inputtypesearch::-webkit-search-decoration { -webkit-appearance: none; }/** Remove inner padding and border in Firefox 4+. */button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }/* Tables *//** Remove most spacing between table cells. */table { border-collapse: collapse; border-spacing: 0; }meta.foundation-mq-small { font-family: only screen and (min-width: 768px); width: 768px; }meta.foundation-mq-medium { font-family: only screen and (min-width:1280px); width: 1280px; }meta.foundation-mq-large { font-family: only screen and (min-width:1440px); width: 1440px; }*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }html, body { font-size: 100%; }body { background: white; color: #222222; padding: 0; margin: 0; font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }a:hover { cursor: pointer; }img, object, embed { max-width: 100%; height: auto; }object, embed { height: 100%; }img { -ms-interpolation-mode: bicubic; }#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }.left { float: left !important; }.right { float: right !important; }.text-left { text-align: left !important; }.text-right { text-align: right !important; }.text-center { text-align: center !important; }.text-justify { text-align: justify !important; }.hide { display: none; }.antialiased { -webkit-font-smoothing: antialiased; }img { display: inline-block; vertical-align: middle; }textarea { height: auto; min-height: 50px; }select { width: 100%; }p.lead { font-size: 1.21875em; line-height: 1.6; }.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #6f6f6f; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }/* Typography resets */div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }/* Default Link Styles */a { color: #2ba6cb; text-decoration: none; line-height: inherit; }a:hover, a:focus { color: #2795b6; }a img { border: none; }/* Default paragraph styles */p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }/* Default header styles */h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; font-weight: bold; font-style: normal; color: #222222; text-rendering: optimizeLegibility; margin-top: 1em; margin-bottom: 0.5em; line-height: 1.2125em; }h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #6f6f6f; line-height: 0; }h1 { font-size: 2.125em; }h2 { font-size: 1.6875em; }h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }h4 { font-size: 1.125em; }h5 { font-size: 1.125em; }h6 { font-size: 1em; }hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }/* Helpful Typography Defaults */em, i { font-style: italic; line-height: inherit; }strong, b { font-weight: bold; line-height: inherit; }small { font-size: 60%; line-height: inherit; }code { font-family: Consolas, Liberation Mono, Courier, monospace; font-weight: bold; color: #7f0a0c; }/* Lists */ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }ul, ol { margin-left: 1.5em; }ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }/* Unordered Lists */ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }ul.square { list-style-type: square; }ul.circle { list-style-type: circle; }ul.disc { list-style-type: disc; }ul.no-bullet { list-style: none; }/* Ordered Lists */ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }/* Definition Lists */dl dt { margin-bottom: 0.3125em; font-weight: bold; }dl dd { margin-bottom: 1.25em; }/* Abbreviations */abbr, acronym { text-transform: uppercase; font-size: 90%; color: #222222; border-bottom: 1px dotted #dddddd; cursor: help; }abbr { text-transform: none; }/* Blockquotes */blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }blockquote cite { display: block; font-size: 0.8125em; color: #555555; }blockquote cite:before { content: \2014 \0020; }blockquote cite a, blockquote cite a:visited { color: #555555; }blockquote, blockquote p { line-height: 1.6; color: #6f6f6f; }/* Microformats */.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; }.vcard li { margin: 0; display: block; }.vcard .fn { font-weight: bold; font-size: 0.9375em; }.vevent .summary { font-weight: bold; }.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } h1 { font-size: 2.75em; } h2 { font-size: 2.3125em; } h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } h4 { font-size: 1.4375em; } }/* Tables */table { background: white; margin-bottom: 1.25em; border: solid 1px #dddddd; }table thead, table tfoot { background: whitesmoke; font-weight: bold; }table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #222222; text-align: left; }table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #222222; }table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f9f9f9; }table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.4; }body { tab-size: 4; word-wrap: anywhere; -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; }table { word-wrap: normal; }h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }object, svg { display: inline-block; vertical-align: middle; }.center { margin-left: auto; margin-right: auto; }.stretch { width: 100%; }.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: ; display: table; }.clearfix:after, .float-group:after { clear: both; }:not(pre).nobreak { word-wrap: normal; }:not(pre).nowrap { white-space: nowrap; }:not(pre).pre-wrap { white-space: pre-wrap; }:not(pre):not(class^L) > code { font-size: inherit; font-style: normal !important; letter-spacing: 0; padding: 0; line-height: inherit; }pre { color: black; font-family: monospace, serif; line-height: 1.4; }pre code, pre pre { color: inherit; font-size: inherit; line-height: inherit; }pre > code { display: block; }pre.nowrap, pre.nowrap pre { white-space: pre; word-wrap: normal; }em em { font-style: normal; }strong strong { font-weight: normal; }.keyseq { color: #555555; }kbd { font-family: Consolas, Liberation Mono, Courier, monospace; display: inline-block; color: #222222; font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }.keyseq kbd:first-child { margin-left: 0; }.keyseq kbd:last-child { margin-right: 0; }.menuseq, .menuref { color: #000; }.menuseq b:not(.caret), .menuref { font-weight: inherit; }.menuseq { word-spacing: -0.02em; }.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }b.button:before { content: ; padding: 0 3px 0 2px; }b.button:after { content: ; padding: 0 2px 0 3px; }#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: ; display: table; }#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }#content { margin-top: 1.25em; }#content:before { content: none; }#header > h1:first-child { color: black; margin-top: 2.25rem; margin-bottom: 0; }#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #dddddd; }#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #dddddd; padding-bottom: 8px; }#header .details { border-bottom: 1px solid #dddddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #555555; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }#header .details span:first-child { margin-left: -0.125em; }#header .details span.email a { color: #6f6f6f; }#header .details br { display: none; }#header .details br + span:before { content: \00a0\2013\00a0; }#header .details br + span.author:before { content: \00a0\22c5\00a0; color: #6f6f6f; }#header .details br + span#revremark:before { content: \00a0|\00a0; }#header #revnumber { text-transform: capitalize; }#header #revnumber:after { content: \00a0; }#content > h1:first-child:not(class) { color: black; border-bottom: 1px solid #dddddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }#toc { border-bottom: 1px solid #dddddd; padding-bottom: 0.5em; }#toc > ul { margin-left: 0.125em; }#toc ul.sectlevel0 > li > a { font-style: italic; }#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }#toc ul { font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; list-style-type: none; }#toc li { line-height: 1.3334; margin-top: 0.3334em; }#toc a { text-decoration: none; }#toc a:active { text-decoration: underline; }#toctitle { color: #6f6f6f; font-size: 1.2em; }@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; } body.toc2 { padding-left: 15em; padding-right: 0; } #toc.toc2 { margin-top: 0 !important; background: #f2f2f2; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; } #toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; } #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; } #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } body.toc2.toc-right { padding-left: 0; padding-right: 15em; } body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } }@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } #toc.toc2 { width: 20em; } #toc.toc2 #toctitle { font-size: 1.375em; } #toc.toc2 > ul { font-size: 0.95em; } #toc.toc2 ul ul { padding-left: 1.25em; } body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }#content #toc { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 0; border-radius: 0; }#content #toc > :first-child { margin-top: 0; }#content #toc > :last-child { margin-bottom: 0; }#footer { max-width: none; background: #222222; padding: 1.25em; }#footer-text { color: #dddddd; line-height: 1.44; }#content { margin-bottom: 0.625em; }.sect1 { padding-bottom: 0.625em; }@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; } .sect1 { padding-bottom: 1.25em; } }.sect1:last-child { padding-bottom: 0; }.sect1 + .sect1 { border-top: 1px solid #dddddd; }#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: \00A7; font-size: 0.85em; display: block; padding-top: 0.1em; }#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #222222; text-decoration: none; }#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #151515; }details, .audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }details > summary:first-of-type { cursor: pointer; display: list-item; outline: none; margin-bottom: 0.75em; }.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }table.tableblock.fit-content > caption.title { white-space: nowrap; width: 0; }.paragraph.lead > p, #preamble > .sectionbody > classparagraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; color: black; }table.tableblock #preamble > .sectionbody > classparagraph:first-of-type p { font-size: inherit; }.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }.admonitionblock > table td.icon { text-align: center; width: 80px; }.admonitionblock > table td.icon img { max-width: none; }.admonitionblock > table td.icon .title { font-weight: bold; font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; text-transform: uppercase; }.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #555555; word-wrap: anywhere; }.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; }.exampleblock > .content > :first-child { margin-top: 0; }.exampleblock > .content > :last-child { margin-bottom: 0; }.sidebarblock { border-style: solid; border-width: 1px; border-color: #d4d4d4; margin-bottom: 1.25em; padding: 1.25em; background: #ededed; -webkit-border-radius: 0; border-radius: 0; }.sidebarblock > :first-child { margin-top: 0; }.sidebarblock > :last-child { margin-bottom: 0; }.sidebarblock > .content > .title { color: #6f6f6f; margin-top: 0; }.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }.literalblock pre, .listingblock > .content > pre { border: 1px solid #cccccc; -webkit-border-radius: 0; border-radius: 0; overflow-x: auto; padding: 0.8em 0.8em 0.65em 0.8em; font-size: 0.8125em; }@media only screen and (min-width: 768px) { .literalblock pre, .listingblock > .content > pre { font-size: 0.90625em; } }@media only screen and (min-width: 1280px) { .literalblock pre, .listingblock > .content > pre { font-size: 1em; } }.literalblock pre, .listingblock > .content > pre:not(.highlight), .listingblock > .content > preclasshighlight, .listingblock > .content > preclass^highlight { background: #eeeeee; }.literalblock.output pre { color: #eeeeee; background-color: black; }.listingblock > .content { position: relative; }.listingblock codedata-lang:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: inherit; opacity: 0.5; }.listingblock:hover codedata-lang:before { display: block; }.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: inherit; opacity: 0.5; }.listingblock.terminal pre .command:not(data-prompt):before { content: $; }.listingblock pre.highlightjs { padding: 0; }.listingblock pre.highlightjs > code { padding: 0.8em 0.8em 0.65em 0.8em; -webkit-border-radius: 0; border-radius: 0; }.prettyprint { background: #eeeeee; }pre.prettyprint .linenums { line-height: 1.4; margin-left: 2em; }pre.prettyprint li { background: none; list-style-type: inherit; padding-left: 0; }pre.prettyprint li codedata-lang:before { opacity: 1; }pre.prettyprint li:not(:first-child) codedata-lang:before { display: none; }table.linenotable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }table.linenotable tdclass { color: inherit; vertical-align: top; padding: 0; line-height: inherit; white-space: normal; }table.linenotable td.code { padding-left: 0.75em; }table.linenotable td.linenos { border-right: 1px solid currentColor; opacity: 0.35; padding-right: 0.5em; }pre.pygments .lineno { border-right: 1px solid currentColor; opacity: 0.35; display: inline-block; margin-right: 0.75em; }pre.pygments .lineno:before { content: ; margin-right: -0.125em; }.quoteblock { margin: 0 1em 1.25em 1.5em; display: table; }.quoteblock:not(.excerpt) > .title { margin-left: -1.5em; margin-bottom: 0.75em; }.quoteblock blockquote, .quoteblock p { color: #6f6f6f; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }.quoteblock blockquote { margin: 0; padding: 0; border: 0; }.quoteblock blockquote:before { content: \201c; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #6f6f6f; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }.quoteblock .attribution { margin-top: 0.75em; margin-right: 0.5ex; text-align: right; }.verseblock { margin: 0 1em 1.25em 1em; }.verseblock pre { font-family: Open Sans, DejaVu Sans, sans; font-size: 1.15rem; color: #6f6f6f; font-weight: 300; text-rendering: optimizeLegibility; }.verseblock pre strong { font-weight: 400; }.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }.quoteblock .attribution br, .verseblock .attribution br { display: none; }.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #555555; }.quoteblock.abstract blockquote:before, .quoteblock.excerpt blockquote:before, .quoteblock .quoteblock blockquote:before { display: none; }.quoteblock.abstract blockquote, .quoteblock.abstract p, .quoteblock.excerpt blockquote, .quoteblock.excerpt p, .quoteblock .quoteblock blockquote, .quoteblock .quoteblock p { line-height: 1.6; word-spacing: 0; }.quoteblock.abstract { margin: 0 1em 1.25em 1em; display: block; }.quoteblock.abstract > .title { margin: 0 0 0.375em 0; font-size: 1.15em; text-align: center; }.quoteblock.excerpt > blockquote, .quoteblock .quoteblock { padding: 0 0 0.25em 1em; border-left: 0.25em solid #dddddd; }.quoteblock.excerpt, .quoteblock .quoteblock { margin-left: 0; }.quoteblock.excerpt blockquote, .quoteblock.excerpt p, .quoteblock .quoteblock blockquote, .quoteblock .quoteblock p { color: inherit; font-size: 1.0625rem; }.quoteblock.excerpt .attribution, .quoteblock .quoteblock .attribution { color: inherit; text-align: left; margin-right: 0; }p.tableblock:last-child { margin-bottom: 0; }td.tableblock > .content { margin-bottom: 1.25em; word-wrap: anywhere; }td.tableblock > .content > :last-child { margin-bottom: -1.25em; }table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dddddd; }table.grid-all > * > tr > * { border-width: 1px; }table.grid-cols > * > tr > * { border-width: 0 1px; }table.grid-rows > * > tr > * { border-width: 1px 0; }table.frame-all { border-width: 1px; }table.frame-ends { border-width: 1px 0; }table.frame-sides { border-width: 0 1px; }table.frame-none > colgroup + * > :first-child > *, table.frame-sides > colgroup + * > :first-child > * { border-top-width: 0; }table.frame-none > :last-child > :last-child > *, table.frame-sides > :last-child > :last-child > * { border-bottom-width: 0; }table.frame-none > * > tr > :first-child, table.frame-ends > * > tr > :first-child { border-left-width: 0; }table.frame-none > * > tr > :last-child, table.frame-ends > * > tr > :last-child { border-right-width: 0; }table.stripes-all tr, table.stripes-odd tr:nth-of-type(odd), table.stripes-even tr:nth-of-type(even), table.stripes-hover tr:hover { background: #f9f9f9; }th.halign-left, td.halign-left { text-align: left; }th.halign-right, td.halign-right { text-align: right; }th.halign-center, td.halign-center { text-align: center; }th.valign-top, td.valign-top { vertical-align: top; }th.valign-bottom, td.valign-bottom { vertical-align: bottom; }th.valign-middle, td.valign-middle { vertical-align: middle; }table thead th, table tfoot th { font-weight: bold; }tbody tr th { display: table-cell; line-height: 1.4; background: whitesmoke; }tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #222222; font-weight: bold; }p.tableblock > code:only-child { background: none; padding: 0; }p.tableblock { font-size: 1em; }ol { margin-left: 1.75em; }ul li ol { margin-left: 1.5em; }dl dd { margin-left: 1.125em; }dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }ul.unstyled, ol.unstyled { margin-left: 0; }ul.checklist { margin-left: 0.625em; }ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }ul.checklist li > p:first-child > inputtypecheckbox:first-child { margin-right: 0.25em; }ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.625em -1.25em; }ul.inline > li { margin-left: 1.25em; }.unstyled dl dt { font-weight: normal; font-style: normal; }ol.arabic { list-style-type: decimal; }ol.decimal { list-style-type: decimal-leading-zero; }ol.loweralpha { list-style-type: lower-alpha; }ol.upperalpha { list-style-type: upper-alpha; }ol.lowerroman { list-style-type: lower-roman; }ol.upperroman { list-style-type: upper-roman; }ol.lowergreek { list-style-type: lower-greek; }.hdlist > table, .colist > table { border: 0; background: none; }.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }td.hdlist1 { font-weight: bold; padding-bottom: 1.25em; }td.hdlist2 { word-wrap: anywhere; }.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }.colist td:not(class):first-child { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }.colist td:not(class):first-child img { max-width: none; }.colist td:not(class):last-child { padding: 0.25em 0; }.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }.imageblock.left { margin: 0.25em 0.625em 1.25em 0; }.imageblock.right { margin: 0.25em 0 1.25em 0.625em; }.imageblock > .title { margin-bottom: 0; }.imageblock.thumb, .imageblock.th { border-width: 6px; }.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }.image.left { margin-right: 0.625em; }.image.right { margin-left: 0.625em; }a.image { text-decoration: none; display: inline-block; }a.image object { pointer-events: none; }sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }sup.footnote a, sup.footnoteref a { text-decoration: none; }sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }#footnotes .footnote:last-of-type { margin-bottom: 0; }#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }.gist .file-data > table td.line-data { width: 99%; }div.unbreakable { page-break-inside: avoid; }.big { font-size: larger; }.small { font-size: smaller; }.underline { text-decoration: underline; }.overline { text-decoration: overline; }.line-through { text-decoration: line-through; }.aqua { color: #00bfbf; }.aqua-background { background-color: #00fafa; }.black { color: black; }.black-background { background-color: black; }.blue { color: #0000bf; }.blue-background { background-color: #0000fa; }.fuchsia { color: #bf00bf; }.fuchsia-background { background-color: #fa00fa; }.gray { color: #606060; }.gray-background { background-color: #7d7d7d; }.green { color: #006000; }.green-background { background-color: #007d00; }.lime { color: #00bf00; }.lime-background { background-color: #00fa00; }.maroon { color: #600000; }.maroon-background { background-color: #7d0000; }.navy { color: #000060; }.navy-background { background-color: #00007d; }.olive { color: #606000; }.olive-background { background-color: #7d7d00; }.purple { color: #600060; }.purple-background { background-color: #7d007d; }.red { color: #bf0000; }.red-background { background-color: #fa0000; }.silver { color: #909090; }.silver-background { background-color: #bcbcbc; }.teal { color: #006060; }.teal-background { background-color: #007d7d; }.white { color: #bfbfbf; }.white-background { background-color: #fafafa; }.yellow { color: #bfbf00; }.yellow-background { background-color: #fafa00; }span.icon > .fa { cursor: default; }a span.icon > .fa { cursor: inherit; }.admonitionblock td.icon class^fa icon- { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }.admonitionblock td.icon .icon-note:before { content: \f05a; color: #207c98; }.admonitionblock td.icon .icon-tip:before { content: \f0eb; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }.admonitionblock td.icon .icon-warning:before { content: \f071; color: #bf6900; }.admonitionblock td.icon .icon-caution:before { content: \f06d; color: #bf3400; }.admonitionblock td.icon .icon-important:before { content: \f06a; color: #bf0000; }.conumdata-value { display: inline-block; color: #fff !important; background-color: #222222; -webkit-border-radius: 50%; border-radius: 50%; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: Open Sans, DejaVu Sans, sans-serif; font-style: normal; font-weight: bold; }.conumdata-value * { color: #fff !important; }.conumdata-value + b { display: none; }.conumdata-value:after { content: attr(data-value); }pre .conumdata-value { position: relative; top: -0.125em; }b.conum * { color: inherit !important; }.conum:not(data-value):empty { display: none; }.literalblock pre, .listingblock pre { background: #eeeeee; }@media screen and (max-width: 768px) { #toc.toc2 { display: none; } }p.lead { font-size: 1.21875em; line-height: 1.6; }.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #6f6f6f; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }/* Typography resets */div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }/* Default Link Styles */a { color: #2ba6cb; text-decoration: none; line-height: inherit; }a:hover, a:focus { color: #2795b6; }a img { border: none; }/* Default paragraph styles */p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }/* Default header styles */h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; font-weight: bold; font-style: normal; color: #404040; text-rendering: optimizeLegibility; margin-top: 1em; margin-bottom: 0.5em; line-height: 1.2125em; }h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #6f6f6f; line-height: 0; }h1 { font-size: 2.125em; }h2 { font-size: 1.6875em; }h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }h4 { font-size: 1.125em; }h5 { font-size: 1.125em; }h6 { font-size: 1em; }hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }/* Helpful Typography Defaults */em, i { font-style: italic; line-height: inherit; }strong, b { font-weight: bold; line-height: inherit; }small { font-size: 60%; line-height: inherit; }code { font-family: Consolas, Liberation Mono, Courier, monospace; font-weight: bold; color: #7f0a0c; }/* Lists */ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }ul, ol { margin-left: 1.5em; }ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }/* Unordered Lists */ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }ul.square { list-style-type: square; }ul.circle { list-style-type: circle; }ul.disc { list-style-type: disc; }ul.no-bullet { list-style: none; }/* Ordered Lists */ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }/* Definition Lists */dl dt { margin-bottom: 0.3125em; font-weight: bold; }dl dd { margin-bottom: 1.25em; }/* Abbreviations */abbr, acronym { text-transform: uppercase; font-size: 90%; color: #222222; border-bottom: 1px dotted #dddddd; cursor: help; }abbr { text-transform: none; }/* Blockquotes */blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }blockquote cite { display: block; font-size: 0.8125em; color: #555555; }blockquote cite:before { content: \2014 \0020; }blockquote cite a, blockquote cite a:visited { color: #555555; }blockquote, blockquote p { line-height: 1.6; color: #6f6f6f; }/* Microformats */.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; }.vcard li { margin: 0; display: block; }.vcard .fn { font-weight: bold; font-size: 0.9375em; }.vevent .summary { font-weight: bold; }.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } h1 { font-size: 2.75em; } h2 { font-size: 2.3125em; } h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } h4 { font-size: 1.4375em; } }/* Tables */table { background: white; margin-bottom: 1.25em; border: solid 1px #dddddd; }table thead, table tfoot { background: whitesmoke; font-weight: bold; }table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #222222; text-align: left; }table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #222222; }table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f9f9f9; }table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.4; }body { tab-size: 4; word-wrap: anywhere; -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; }table { word-wrap: normal; }h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }object, svg { display: inline-block; vertical-align: middle; }.center { margin-left: auto; margin-right: auto; }.stretch { width: 100%; }.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: ; display: table; }.clearfix:after, .float-group:after { clear: both; }:not(pre).nobreak { word-wrap: normal; }:not(pre).nowrap { white-space: nowrap; }:not(pre).pre-wrap { white-space: pre-wrap; }:not(pre):not(class^L) > code { font-size: inherit; font-style: normal !important; letter-spacing: 0; padding: 0; line-height: inherit; }pre { color: black; font-family: monospace, serif; line-height: 1.4; }pre code, pre pre { color: inherit; font-size: inherit; line-height: inherit; }pre > code { display: block; }pre.nowrap, pre.nowrap pre { white-space: pre; word-wrap: normal; }em em { font-style: normal; }strong strong { font-weight: normal; }.keyseq { color: #555555; }kbd { font-family: Consolas, Liberation Mono, Courier, monospace; display: inline-block; color: #222222; font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }.keyseq kbd:first-child { margin-left: 0; }.keyseq kbd:last-child { margin-right: 0; }.menuseq, .menuref { color: #000; }.menuseq b:not(.caret), .menuref { font-weight: inherit; }.menuseq { word-spacing: -0.02em; }.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }b.button:before { content: ; padding: 0 3px 0 2px; }b.button:after { content: ; padding: 0 2px 0 3px; }#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: ; display: table; }#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }#content { margin-top: 1.25em; }#content:before { content: none; }#header > h1:first-child { color: black; margin-top: 2.25rem; margin-bottom: 0; }#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #dddddd; }#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #dddddd; padding-bottom: 8px; }#header .details { border-bottom: 1px solid #dddddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #555555; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }#header .details span:first-child { margin-left: -0.125em; }#header .details span.email a { color: #6f6f6f; }#header .details br { display: none; }#header .details br + span:before { content: \00a0\2013\00a0; }#header .details br + span.author:before { content: \00a0\22c5\00a0; color: #6f6f6f; }#header .details br + span#revremark:before { content: \00a0|\00a0; }#header #revnumber { text-transform: capitalize; }#header #revnumber:after { content: \00a0; }#content > h1:first-child:not(class) { color: black; border-bottom: 1px solid #dddddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }#toc { border-bottom: 1px solid #dddddd; padding-bottom: 0.5em; }#toc > ul { margin-left: 0.125em; }#toc ul.sectlevel0 > li > a { font-style: italic; }#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }#toc ul { font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; list-style-type: none; }#toc li { line-height: 1.3334; margin-top: 0.3334em; }#toc a { text-decoration: none; }#toc a:active { text-decoration: underline; }#toctitle { color: #6f6f6f; font-size: 1.2em; }@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; } body.toc2 { padding-left: 15em; padding-right: 0; } #toc.toc2 { margin-top: 0 !important; background: #f2f2f2; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; } #toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; } #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; } #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } body.toc2.toc-right { padding-left: 0; padding-right: 15em; } body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } }@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } #toc.toc2 { width: 20em; } #toc.toc2 #toctitle { font-size: 1.375em; } #toc.toc2 > ul { font-size: 0.95em; } #toc.toc2 ul ul { padding-left: 1.25em; } body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }#content #toc { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 0; border-radius: 0; }#content #toc > :first-child { margin-top: 0; }#content #toc > :last-child { margin-bottom: 0; }#footer { max-width: none; background: #222222; padding: 1.25em; }#footer-text { color: #dddddd; line-height: 1.44; }#content { margin-bottom: 0.625em; }.sect1 { padding-bottom: 0.625em; }@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; } .sect1 { padding-bottom: 1.25em; } }.sect1:last-child { padding-bottom: 0; }.sect1 + .sect1 { border-top: 1px solid #dddddd; }#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: \00A7; font-size: 0.85em; display: block; padding-top: 0.1em; }#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #404040; text-decoration: none; }#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #333333; }details, .audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }details > summary:first-of-type { cursor: pointer; display: list-item; outline: none; margin-bottom: 0.75em; }.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }table.tableblock.fit-content > caption.title { white-space: nowrap; width: 0; }.paragraph.lead > p, #preamble > .sectionbody > classparagraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; color: black; }table.tableblock #preamble > .sectionbody > classparagraph:first-of-type p { font-size: inherit; }.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }.admonitionblock > table td.icon { text-align: center; width: 80px; }.admonitionblock > table td.icon img { max-width: none; }.admonitionblock > table td.icon .title { font-weight: bold; font-family: Helvetica Neue, Helvetica, Helvetica, Arial, sans-serif; text-transform: uppercase; }.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #555555; word-wrap: anywhere; }.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; }.exampleblock > .content > :first-child { margin-top: 0; }.exampleblock > .content > :last-child { margin-bottom: 0; }.sidebarblock { border-style: solid; border-width: 1px; border-color: #d4d4d4; margin-bottom: 1.25em; padding: 1.25em; background: #ededed; -webkit-border-radius: 0; border-radius: 0; }.sidebarblock > :first-child { margin-top: 0; }.sidebarblock > :last-child { margin-bottom: 0; }.sidebarblock > .content > .title { color: #6f6f6f; margin-top: 0; }.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }.literalblock pre, .listingblock > .content > pre { border: 1px solid #cccccc; -webkit-border-radius: 0; border-radius: 0; overflow-x: auto; padding: 0.8em 0.8em 0.65em 0.8em; font-size: 0.8125em; }@media only screen and (min-width: 768px) { .literalblock pre, .listingblock > .content > pre { font-size: 0.90625em; } }@media only screen and (min-width: 1280px) { .literalblock pre, .listingblock > .content > pre { font-size: 1em; } }.literalblock pre, .listingblock > .content > pre:not(.highlight), .listingblock > .content > preclasshighlight, .listingblock > .content > preclass^highlight { background: #eeeeee; }.literalblock.output pre { color: #eeeeee; background-color: black; }.listingblock > .content { position: relative; }.listingblock codedata-lang:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: inherit; opacity: 0.5; }.listingblock:hover codedata-lang:before { display: block; }.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: inherit; opacity: 0.5; }.listingblock.terminal pre .command:not(data-prompt):before { content: $; }.listingblock pre.highlightjs { padding: 0; }.listingblock pre.highlightjs > code { padding: 0.8em 0.8em 0.65em 0.8em; -webkit-border-radius: 0; border-radius: 0; }.prettyprint { background: #eeeeee; }pre.prettyprint .linenums { line-height: 1.4; margin-left: 2em; }pre.prettyprint li { background: none; list-style-type: inherit; padding-left: 0; }pre.prettyprint li codedata-lang:before { opacity: 1; }pre.prettyprint li:not(:first-child) codedata-lang:before { display: none; }table.linenotable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }table.linenotable tdclass { color: inherit; vertical-align: top; padding: 0; line-height: inherit; white-space: normal; }table.linenotable td.code { padding-left: 0.75em; }table.linenotable td.linenos { border-right: 1px solid currentColor; opacity: 0.35; padding-right: 0.5em; }pre.pygments .lineno { border-right: 1px solid currentColor; opacity: 0.35; display: inline-block; margin-right: 0.75em; }pre.pygments .lineno:before { content: ; margin-right: -0.125em; }.quoteblock { margin: 0 1em 1.25em 1.5em; display: table; }.quoteblock:not(.excerpt) > .title { margin-left: -1.5em; margin-bottom: 0.75em; }.quoteblock blockquote, .quoteblock p { color: #6f6f6f; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }.quoteblock blockquote { margin: 0; padding: 0; border: 0; }.quoteblock blockquote:before { content: \201c; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #6f6f6f; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }.quoteblock .attribution { margin-top: 0.75em; margin-right: 0.5ex; text-align: right; }.verseblock { margin: 0 1em 1.25em 1em; }.verseblock pre { font-family: Open Sans, DejaVu Sans, sans; font-size: 1.15rem; color: #6f6f6f; font-weight: 300; text-rendering: optimizeLegibility; }.verseblock pre strong { font-weight: 400; }.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }.quoteblock .attribution br, .verseblock .attribution br { display: none; }.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #555555; }.quoteblock.abstract blockquote:before, .quoteblock.excerpt blockquote:before, .quoteblock .quoteblock blockquote:before { display: none; }.quoteblock.abstract blockquote, .quoteblock.abstract p, .quoteblock.excerpt blockquote, .quoteblock.excerpt p, .quoteblock .quoteblock blockquote, .quoteblock .quoteblock p { line-height: 1.6; word-spacing: 0; }.quoteblock.abstract { margin: 0 1em 1.25em 1em; display: block; }.quoteblock.abstract > .title { margin: 0 0 0.375em 0; font-size: 1.15em; text-align: center; }.quoteblock.excerpt > blockquote, .quoteblock .quoteblock { padding: 0 0 0.25em 1em; border-left: 0.25em solid #dddddd; }.quoteblock.excerpt, .quoteblock .quoteblock { margin-left: 0; }.quoteblock.excerpt blockquote, .quoteblock.excerpt p, .quoteblock .quoteblock blockquote, .quoteblock .quoteblock p { color: inherit; font-size: 1.0625rem; }.quoteblock.excerpt .attribution, .quoteblock .quoteblock .attribution { color: inherit; text-align: left; margin-right: 0; }p.tableblock:last-child { margin-bottom: 0; }td.tableblock > .content { margin-bottom: 1.25em; word-wrap: anywhere; }td.tableblock > .content > :last-child { margin-bottom: -1.25em; }table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dddddd; }table.grid-all > * > tr > * { border-width: 1px; }table.grid-cols > * > tr > * { border-width: 0 1px; }table.grid-rows > * > tr > * { border-width: 1px 0; }table.frame-all { border-width: 1px; }table.frame-ends { border-width: 1px 0; }table.frame-sides { border-width: 0 1px; }table.frame-none > colgroup + * > :first-child > *, table.frame-sides > colgroup + * > :first-child > * { border-top-width: 0; }table.frame-none > :last-child > :last-child > *, table.frame-sides > :last-child > :last-child > * { border-bottom-width: 0; }table.frame-none > * > tr > :first-child, table.frame-ends > * > tr > :first-child { border-left-width: 0; }table.frame-none > * > tr > :last-child, table.frame-ends > * > tr > :last-child { border-right-width: 0; }table.stripes-all tr, table.stripes-odd tr:nth-of-type(odd), table.stripes-even tr:nth-of-type(even), table.stripes-hover tr:hover { background: #f9f9f9; }th.halign-left, td.halign-left { text-align: left; }th.halign-right, td.halign-right { text-align: right; }th.halign-center, td.halign-center { text-align: center; }th.valign-top, td.valign-top { vertical-align: top; }th.valign-bottom, td.valign-bottom { vertical-align: bottom; }th.valign-middle, td.valign-middle { vertical-align: middle; }table thead th, table tfoot th { font-weight: bold; }tbody tr th { display: table-cell; line-height: 1.4; background: whitesmoke; }tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #222222; font-weight: bold; }p.tableblock > code:only-child { background: none; padding: 0; }p.tableblock { font-size: 1em; }ol { margin-left: 1.75em; }ul li ol { margin-left: 1.5em; }dl dd { margin-left: 1.125em; }dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }ul.unstyled, ol.unstyled { margin-left: 0; }ul.checklist { margin-left: 0.625em; }ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }ul.checklist li > p:first-child > inputtypecheckbox:first-child { margin-right: 0.25em; }ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.625em -1.25em; }ul.inline > li { margin-left: 1.25em; }.unstyled dl dt { font-weight: normal; font-style: normal; }ol.arabic { list-style-type: decimal; }ol.decimal { list-style-type: decimal-leading-zero; }ol.loweralpha { list-style-type: lower-alpha; }ol.upperalpha { list-style-type: upper-alpha; }ol.lowerroman { list-style-type: lower-roman; }ol.upperroman { list-style-type: upper-roman; }ol.lowergreek { list-style-type: lower-greek; }.hdlist > table, .colist > table { border: 0; background: none; }.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }td.hdlist1 { font-weight: bold; padding-bottom: 1.25em; }td.hdlist2 { word-wrap: anywhere; }.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }.colist td:not(class):first-child { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }.colist td:not(class):first-child img { max-width: none; }.colist td:not(class):last-child { padding: 0.25em 0; }.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }.imageblock.left { margin: 0.25em 0.625em 1.25em 0; }.imageblock.right { margin: 0.25em 0 1.25em 0.625em; }.imageblock > .title { margin-bottom: 0; }.imageblock.thumb, .imageblock.th { border-width: 6px; }.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }.image.left { margin-right: 0.625em; }.image.right { margin-left: 0.625em; }a.image { text-decoration: none; display: inline-block; }a.image object { pointer-events: none; }sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }sup.footnote a, sup.footnoteref a { text-decoration: none; }sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }#footnotes .footnote:last-of-type { margin-bottom: 0; }#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }.gist .file-data > table td.line-data { width: 99%; }div.unbreakable { page-break-inside: avoid; }.big { font-size: larger; }.small { font-size: smaller; }.underline { text-decoration: underline; }.overline { text-decoration: overline; }.line-through { text-decoration: line-through; }.aqua { color: #00bfbf; }.aqua-background { background-color: #00fafa; }.black { color: black; }.black-background { background-color: black; }.blue { color: #0000bf; }.blue-background { background-color: #0000fa; }.fuchsia { color: #bf00bf; }.fuchsia-background { background-color: #fa00fa; }.gray { color: #606060; }.gray-background { background-color: #7d7d7d; }.green { color: #006000; }.green-background { background-color: #007d00; }.lime { color: #00bf00; }.lime-background { background-color: #00fa00; }.maroon { color: #600000; }.maroon-background { background-color: #7d0000; }.navy { color: #000060; }.navy-background { background-color: #00007d; }.olive { color: #606000; }.olive-background { background-color: #7d7d00; }.purple { color: #600060; }.purple-background { background-color: #7d007d; }.red { color: #bf0000; }.red-background { background-color: #fa0000; }.silver { color: #909090; }.silver-background { background-color: #bcbcbc; }.teal { color: #006060; }.teal-background { background-color: #007d7d; }.white { color: #bfbfbf; }.white-background { background-color: #fafafa; }.yellow { color: #bfbf00; }.yellow-background { background-color: #fafa00; }span.icon > .fa { cursor: default; }a span.icon > .fa { cursor: inherit; }.admonitionblock td.icon class^fa icon- { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }.admonitionblock td.icon .icon-note:before { content: \f05a; color: #207c98; }.admonitionblock td.icon .icon-tip:before { content: \f0eb; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }.admonitionblock td.icon .icon-warning:before { content: \f071; color: #bf6900; }.admonitionblock td.icon .icon-caution:before { content: \f06d; color: #bf3400; }.admonitionblock td.icon .icon-important:before { content: \f06a; color: #bf0000; }.conumdata-value { display: inline-block; color: #fff !important; background-color: #222222; -webkit-border-radius: 50%; border-radius: 50%; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: Open Sans, DejaVu Sans, sans-serif; font-style: normal; font-weight: bold; }.conumdata-value * { color: #fff !important; }.conumdata-value + b { display: none; }.conumdata-value:after { content: attr(data-value); }pre .conumdata-value { position: relative; top: -0.125em; }b.conum * { color: inherit !important; }.conum:not(data-value):empty { display: none; }.must-keyword { color: red; }.should-keyword { color: darkgoldenrod; }.may-keyword { color: green; }.status-code, .status-code:link, .status-code:visited, .status-code:hover, .status-code:active { color: black; font-weight: bold; }.sect1 { max-width: 45em; }#content #toc { max-width: 45em; }code { font-size: .85em !important; }p > code { background-color: #f0f0f0; padding: .1em .4em .1em .4em !important; font-size: .9em !important; color: inherit; }a > code { background-color: #f0f0f0; padding: .1em .4em .1em .4em !important; font-size: .9em !important; color: black; }.literalblock pre, .literalblock preclass, .listingblock pre, .listingblock preclass { padding: .5em !important; }#toc a { color: #364149; }/style>link relstylesheet hrefhttps://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.3/styles/github.min.css>meta namerobots contentnoindex />/head>body classarticle>div idheader>/div>div idcontent>div classsect1>h2 id_bsh_ci_api_guidelines>a classlink href#_bsh_ci_api_guidelines>BSH CI API Guidelines/a>/h2>div classsectionbody>div classparagraph>p>a hrefhttps://github.com/bshgroup/API-Guidelines>Github Repository Link/a>/p>/div>div classimageblock>div classcontent>img srcassets/bsh-logo.png altBSH Logo>/div>/div>div idtoc classtoc>div idtoctitle classtitle>Table of Contents/div>ul classsectlevel1>li>a href#_bsh_ci_api_guidelines>BSH CI API Guidelines/a>/li>li>a href#introduction>1. Introduction/a>ul classsectlevel2>li>a href#conventions-used-in-these-guidelines>1.1. Conventions used in these guidelines/a>/li>li>a href#purpose-of-these-guidelines>1.2. Purpose of these guidelines/a>/li>/ul>/li>li>a href#principles>2. Principles/a>ul classsectlevel2>li>a href#api-design-principles>2.1. API design principles/a>/li>li>a href#api-as-a-product>2.2. API as a product/a>/li>li>a href#api-first>2.3. API first/a>/li>/ul>/li>li>a href#general-guidelines>3. General guidelines/a>ul classsectlevel2>li>a href#100>3.1. span classmust-keyword>strong>MUST/strong>/span> follow API first principle/a>/li>li>a href#101>3.2. span classmust-keyword>strong>MUST/strong>/span> provide API specification using OpenAPI/a>/li>li>a href#102>3.3. span classshould-keyword>strong>SHOULD/strong>/span> provide API user manual/a>/li>li>a href#103>3.4. span classmust-keyword>strong>MUST/strong>/span> write APIs using the American English language/a>/li>li>a href#105>3.5. span classmust-keyword>strong>MUST/strong>/span> use source control for API specifications/a>/li>li>a href#218>3.6. span classmust-keyword>strong>MUST/strong>/span> contain API meta information/a>/li>li>a href#116>3.7. span classmust-keyword>strong>MUST/strong>/span> use semantic versioning/a>/li>/ul>/li>li>a href#compatibility>4. Compatibility/a>ul classsectlevel2>li>a href#106>4.1. span classmust-keyword>strong>MUST/strong>/span> not break backward compatibility/a>/li>li>a href#107>4.2. span classshould-keyword>strong>SHOULD/strong>/span> prefer compatible extensions/a>/li>li>a href#108>4.3. span classmust-keyword>strong>MUST/strong>/span> prepare clients accept compatible API extensions/a>/li>li>a href#109>4.4. span classshould-keyword>strong>SHOULD/strong>/span> design APIs conservatively/a>/li>li>a href#110>4.5. span classmust-keyword>strong>MUST/strong>/span> always return JSON objects as top-level data structures/a>/li>li>a href#112>4.6. span classshould-keyword>strong>SHOULD/strong>/span> used open-ended list of values (code>x-extensible-enum/code>) for enumerations/a>/li>li>a href#113>4.7. span classshould-keyword>strong>SHOULD/strong>/span> avoid versioning/a>/li>li>a href#115>4.8. span classmust-keyword>strong>MUST/strong>/span> use URI versioning/a>/li>/ul>/li>li>a href#deprecation>5. Deprecation/a>ul classsectlevel2>li>a href#185>5.1. span classmust-keyword>strong>MUST/strong>/span> obtain approval of clients before API shut down/a>/li>li>a href#186>5.2. span classmust-keyword>strong>MUST/strong>/span> collect external partner consent on deprecation time span/a>/li>li>a href#187>5.3. span classmust-keyword>strong>MUST/strong>/span> reflect deprecation in API specifications/a>/li>li>a href#188>5.4. span classmust-keyword>strong>MUST/strong>/span> monitor usage of deprecated API scheduled for sunset/a>/li>li>a href#191>5.5. span classmust-keyword>strong>MUST/strong>/span> not start using deprecated APIs/a>/li>/ul>/li>li>a href#json-guidelines>6. JSON guidelines/a>ul classsectlevel2>li>a href#118>6.1. span classmust-keyword>strong>MUST/strong>/span> property names must be alphanumeric ASCII camelCase/a>/li>li>a href#240>6.2. span classshould-keyword>strong>SHOULD/strong>/span> declare enum values using UPPER_SNAKE_CASE format/a>/li>li>a href#216>6.3. span classshould-keyword>strong>SHOULD/strong>/span> define maps using code>additionalProperties/code>/a>/li>li>a href#120>6.4. span classshould-keyword>strong>SHOULD/strong>/span> pluralize array names/a>/li>li>a href#122>6.5. span classmust-keyword>strong>MUST/strong>/span> not use code>null/code> for boolean properties/a>/li>li>a href#123>6.6. span classmust-keyword>strong>MUST/strong>/span> use same semantics for code>null/code> and absent properties/a>/li>li>a href#124>6.7. span classmust-keyword>strong>MUST/strong>/span> not use code>null/code> for empty arrays/a>/li>li>a href#235>6.8. span classshould-keyword>strong>SHOULD/strong>/span> name date/time properties with code>Date/code> suffix/a>/li>li>a href#126>6.9. span classshould-keyword>strong>SHOULD/strong>/span> define dates properties compliant with RFC 3339/a>/li>li>a href#127>6.10. span classshould-keyword>strong>SHOULD/strong>/span> define time durations and intervals properties conform to ISO 8601/a>/li>/ul>/li>li>a href#data-formats>7. Data formats/a>ul classsectlevel2>li>a href#167>7.1. span classmust-keyword>strong>MUST/strong>/span> use JSON as payload data interchange format/a>/li>li>a href#172>7.2. span classshould-keyword>strong>SHOULD/strong>/span> prefer standard media type name code>application/json/code>/a>/li>li>a href#168>7.3. span classmay-keyword>strong>MAY/strong>/span> pass non-JSON media types using data specific standard formats/a>/li>li>a href#238>7.4. span classshould-keyword>strong>SHOULD/strong>/span> use standardized property formats/a>/li>li>a href#170>7.5. span classshould-keyword>strong>SHOULD/strong>/span> use standards for country, language and currency codes/a>/li>li>a href#171>7.6. span classmust-keyword>strong>MUST/strong>/span> define format for number and integer types/a>/li>/ul>/li>li>a href#common-data-types>8. Common data types/a>ul classsectlevel2>li>a href#173>8.1. span classmust-keyword>strong>MUST/strong>/span> use the common money object/a>/li>li>a href#174>8.2. span classmust-keyword>strong>MUST/strong>/span> use common field names and semantics/a>/li>/ul>/li>li>a href#api-naming>9. API naming/a>ul classsectlevel2>li>a href#129>9.1. span classmust-keyword>strong>MUST/strong>/span> use lowercase separate words with hyphens for path segments/a>/li>li>a href#130>9.2. span classmust-keyword>strong>MUST/strong>/span> use snake_case (never camelCase) for query parameters/a>/li>li>a href#132>9.3. span classshould-keyword>strong>SHOULD/strong>/span> prefer hyphenated-pascal-case for HTTP header fields/a>/li>li>a href#134>9.4. span classmust-keyword>strong>MUST/strong>/span> pluralize resource names/a>/li>li>a href#137>9.5. span classmust-keyword>strong>MUST/strong>/span> stick to conventional query parameters/a>/li>/ul>/li>li>a href#resources>10. Resources/a>ul classsectlevel2>li>a href#138>10.1. span classmust-keyword>strong>MUST/strong>/span> avoid actions - think about resources/a>/li>li>a href#140>10.2. span classshould-keyword>strong>SHOULD/strong>/span> define em>useful/em> resources/a>/li>li>a href#141>10.3. span classmust-keyword>strong>MUST/strong>/span> keep URLs verb-free/a>/li>li>a href#142>10.4. span classmust-keyword>strong>MUST/strong>/span> use domain-specific resource names/a>/li>li>a href#228>10.5. span classmust-keyword>strong>MUST/strong>/span> use URL-friendly resource identifiers: a-zA-Z0-9:._\-/*/a>/li>li>a href#143>10.6. span classmust-keyword>strong>MUST/strong>/span> identify resources and sub-resources via path segments/a>/li>li>a href#241>10.7. span classmay-keyword>strong>MAY/strong>/span> expose compound keys as resource identifiers/a>/li>li>a href#145>10.8. span classmay-keyword>strong>MAY/strong>/span> consider using (non-)nested URLs/a>/li>li>a href#144>10.9. span classshould-keyword>strong>SHOULD/strong>/span> only use UUIDs if necessary/a>/li>li>a href#146>10.10. span classshould-keyword>strong>SHOULD/strong>/span> limit number of resource types/a>/li>li>a href#147>10.11. span classshould-keyword>strong>SHOULD/strong>/span> limit number of sub-resource levels/a>/li>/ul>/li>li>a href#http-requests>11. HTTP requests/a>ul classsectlevel2>li>a href#148>11.1. span classmust-keyword>strong>MUST/strong>/span> use HTTP methods correctly/a>/li>li>a href#149>11.2. span classmust-keyword>strong>MUST/strong>/span> fulfill common method properties/a>/li>li>a href#236>11.3. span classshould-keyword>strong>SHOULD/strong>/span> design simple query languages using query parameters/a>/li>li>a href#237>11.4. span classshould-keyword>strong>SHOULD/strong>/span> design complex query languages using JSON/a>/li>/ul>/li>li>a href#http-status-codes-and-errors>12. HTTP status codes and errors/a>ul classsectlevel2>li>a href#151>12.1. span classmust-keyword>strong>MUST/strong>/span> specify success and error responses/a>/li>li>a href#150>12.2. span classmust-keyword>strong>MUST/strong>/span> use standard HTTP status codes/a>/li>li>a href#220>12.3. span classmust-keyword>strong>MUST/strong>/span> use most specific HTTP status codes/a>/li>li>a href#176>12.4. span classmust-keyword>strong>MUST/strong>/span> support problem JSON/a>/li>li>a href#177>12.5. span classmust-keyword>strong>MUST/strong>/span> not expose stack traces/a>/li>/ul>/li>li>a href#performance>13. Performance/a>ul classsectlevel2>li>a href#155>13.1. span classshould-keyword>strong>SHOULD/strong>/span> reduce bandwidth needs and improve responsiveness/a>/li>li>a href#156>13.2. span classshould-keyword>strong>SHOULD/strong>/span> use code>gzip/code> compression/a>/li>li>a href#158>13.3. span classshould-keyword>strong>SHOULD/strong>/span> allow optional embedding of sub-resources/a>/li>li>a href#159>13.4. span classmust-keyword>strong>MUST/strong>/span> support pagination/a>/li>/ul>/li>li>a href#hypermedia>14. Hypermedia/a>ul classsectlevel2>li>a href#162>14.1. span classmust-keyword>strong>MUST/strong>/span> use REST maturity level 2/a>/li>li>a href#163>14.2. span classmay-keyword>strong>MAY/strong>/span> use REST maturity level 3 - HATEOAS/a>/li>/ul>/li>li>a href#proprietary-headers>15. Proprietary headers/a>ul classsectlevel2>li>a href#183>15.1. span classshould-keyword>strong>SHOULD/strong>/span> use only the specified proprietary BSH headers/a>/li>li>a href#184>15.2. span classmust-keyword>strong>MUST/strong>/span> propagate proprietary headers/a>/li>li>a href#233>15.3. span classmust-keyword>strong>MUST/strong>/span> support code>X-Flow-ID/code>/a>/li>/ul>/li>li>a href#security>16. Security/a>ul classsectlevel2>li>a href#104>16.1. span classmust-keyword>strong>MUST/strong>/span> document authentication and authorization mechanisms/a>/li>/ul>/li>li>a href#appendix>Appendix A: Appendix/a>ul classsectlevel2>li>a href#specifications-and-standards>A.1. Specifications and standards/a>/li>li>a href#_attribution>A.2. Attribution/a>/li>/ul>/li>/ul>/div>/div>/div>div classsect1>h2 idintroduction>a classlink href#introduction>1. Introduction/a>/h2>div classsectionbody>div classparagraph>p>Our software architecture centers around decoupled microservicesthat provide functionality via RESTful APIs with a JSON payload. Smallengineering teams own, deploy and operate these microservices.Our APIs most purely express what our systems do,and are therefore highly valuable business assets./p>/div>div classparagraph>p>With this in mind, we’ve adopted API First as one of our keyengineering principles. Microservices development begins with APIdefinition outside the code and ideally involves ample peer-reviewfeedback to achieve high-quality APIs. API First encompasses a set ofquality-related standards and fosters a peer review culture including alightweight review procedure. We encourage our teams to follow them toensure that our APIs:/p>/div>div classulist>ul>li>p>are easy to understand and learn/p>/li>li>p>are general and abstracted from specific implementation and use cases/p>/li>li>p>are robust and easy to use/p>/li>li>p>have a common look and feel/p>/li>li>p>follow a consistent RESTful style and syntax/p>/li>li>p>are consistent with other teams’ APIs and our global architecture/p>/li>/ul>/div>div classparagraph>p>Ideally all APIs will look like the same author created them./p>/div>div classsect2>h3 idconventions-used-in-these-guidelines>a classlink href#conventions-used-in-these-guidelines>1.1. Conventions used in these guidelines/a>/h3>div classparagraph>p>The requirement level keywords MUST, MUST NOT, REQUIRED, SHALL,SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, andOPTIONAL used in this document (case insensitive) are to beinterpreted as described in a hrefhttps://www.ietf.org/rfc/rfc2119.txt>RFC2119/a>./p>/div>/div>div classsect2>h3 idpurpose-of-these-guidelines>a classlink href#purpose-of-these-guidelines>1.2. Purpose of these guidelines/a>/h3>div classparagraph>p>The purpose of these guidelines is to define standards tosuccessfully establish consistent API look and feel quality.Teams are responsible to fulfill these guidelines during API developmentand are encouraged to contribute to guideline evolution via pull requests./p>/div>div classparagraph>p>These guidelines will, to some extent, remain work in progress as ourwork evolves, but teams can confidently follow and trust them./p>/div>div classparagraph>p>In case guidelines are changing, following rules apply:/p>/div>div classulist>ul>li>p>existing APIs don’t have to be changed, but we recommend it/p>/li>li>p>clients of existing APIs have to cope with these APIs based onoutdated rules/p>/li>li>p>new APIs have to respect the current guidelines/p>/li>/ul>/div>/div>/div>/div>div classsect1>h2 idprinciples>a classlink href#principles>2. Principles/a>/h2>div classsectionbody>div classsect2>h3 idapi-design-principles>a classlink href#api-design-principles>2.1. API design principles/a>/h3>div classparagraph>p>We apply the RESTful web service principles to all kind of application(micro-) service components, independently from whether they providefunctionality via the internet or intranet./p>/div>div classulist>ul>li>p>We prefer REST-based APIs with JSON payloads/p>/li>li>p>We prefer systems to be truly RESTfulsup classfootnote id_footnote_fielding-restful>a id_footnoteref_1 classfootnote href#_footnotedef_1 titleView footnote.>1/a>/sup>/p>/li>/ul>/div>div classparagraph>p>An important principle for API design and usage is Postel’sLaw, aka a hrefhttp://en.wikipedia.org/wiki/Robustness_principle>TheRobustness Principle/a> (see also a hrefhttps://tools.ietf.org/html/rfc1122>RFC 1122/a>):/p>/div>div classulist>ul>li>p>Be liberal in what you accept, be conservative in what you send/p>/li>/ul>/div>/div>div classsect2>h3 idapi-as-a-product>a classlink href#api-as-a-product>2.2. API as a product/a>/h3>div classparagraph>p>Platform products provide their functionality via (public) APIs; hence,the design of our APIs should be based on the API as a Productprinciple:/p>/div>div classulist>ul>li>p>Treat your API as product and act like a product owner/p>/li>li>p>Put yourself into the place of your customers; be an advocate fortheir needs/p>/li>li>p>Emphasize simplicity, comprehensibility, and usability of APIs tomake them irresistible for client engineers/p>/li>li>p>Actively improve and maintain API consistency over the long term/p>/li>li>p>Make use of customer feedback and provide service level support/p>/li>/ul>/div>div classparagraph>p>Understand the concrete use cases of your customers and carefully checkthe trade-offs of your API design variants with a product mindset. Avoid short-termimplementation optimizations at the expense of unnecessary client sideobligations, and have a high attention on API quality and clientdeveloper experience./p>/div>div classparagraph>p>API as a Product is closely related to our a href#100>API First principle/a>(see next chapter) which is more focused on how we engineer high quality APIs./p>/div>/div>div classsect2>h3 idapi-first>a classlink href#api-first>2.3. API first/a>/h3>div classparagraph>p>In a nutshell API First requires two aspects:/p>/div>div classulist>ul>li>p>define APIs first, before coding its implementation, using a standard specificationlanguage/p>/li>li>p>get early review feedback from peers and client developers/p>/li>/ul>/div>div classparagraph>p>Elements of API First are also this API Guidelines and a standardizedAPI review process as to get early review feedback frompeers and client developers. Peer review is important for us to get highquality APIs, to enable architectural and design alignment and tosupported development of client applications decoupled from serviceprovider engineering life cycle./p>/div>div classparagraph>p>It is important to learn, that API First is strong>not in conflict with theagile development principles/strong> that we love. Service applications shouldevolve incrementally — and so its APIs. Of course, our API specificationwill and should evolve iteratively in different cycles; however, eachstarting with draft status and em>early/em> team and peer review feedback.API may change and profit from implementation concerns and automatedtesting feedback. API evolution during development life cycle mayinclude breaking changes for not yet productive features and as long aswe have aligned the changes with the clients. Hence, API First doesem>not/em> mean that you must have 100% domain and requirement understandingand can never produce code before you have defined the complete API andget it confirmed by peer review./p>/div>div classparagraph>p>On the other hand, API First obviously is in conflict with the badpractice of publishing API definition and asking for peer review afterthe service integration or even the service productive operation hasstarted. It is crucial to request and get early feedback — as early aspossible, but not before the API changes are comprehensive with focusto the next evolution step and have a certain quality (including APIGuideline compliance), already confirmed via team internal reviews./p>/div>/div>/div>/div>div classsect1>h2 idgeneral-guidelines>a classlink href#general-guidelines>3. General guidelines/a>/h2>div classsectionbody>div classparagraph>p>The titles are marked with the corresponding labels: span classmust-keyword>strong>MUST/strong>/span>,span classshould-keyword>strong>SHOULD/strong>/span>, span classmay-keyword>strong>MAY/strong>/span>./p>/div>div classsect2>h3 id100>a classlink href#100>3.1. span classmust-keyword>strong>MUST/strong>/span> follow API first principle/a>/h3>div classparagraph>p>You must follow the a href#api-first>API First Principle/a>, more specifically:/p>/div>div classulist>ul>li>p>You must define APIs first, before coding its implementation, a href#101>usingOpenAPI as specification language/a>/p>/li>li>p>You must design your APIs consistently with these guidelines; use ourAPI Linter Service for automated rule checks./p>/li>li>p>You must call for early review feedback from peers and client developers./p>/li>/ul>/div>/div>div classsect2>h3 id101>a classlink href#101>3.2. span classmust-keyword>strong>MUST/strong>/span> provide API specification using OpenAPI/a>/h3>div classparagraph>p>We use the a hrefhttp://swagger.io/specification/>OpenAPI 3 specification/a> as standardto define API specification files. API designers are required to provide the APIspecification using a single strong>self-contained/strong> file (YAML is preferred to improve readability)./p>/div>div classparagraph>p>The API specification files should be subject to version control using a sourcecode management system./p>/div>/div>div classsect2>h3 id102>a classlink href#102>3.3. span classshould-keyword>strong>SHOULD/strong>/span> provide API user manual/a>/h3>div classparagraph>p>In addition to the API Specification, it is good practice to provide an APIuser manual to improve client developer experience, especially of engineersthat are less experienced in using this API. A helpful API user manualtypically describes the following API aspects:/p>/div>div classulist>ul>li>p>API scope, purpose, and use cases/p>/li>li>p>concrete examples of API usage/p>/li>li>p>edge cases, error situation details, and repair hints/p>/li>li>p>architecture context and major dependencies - including figures andsequence flows/p>/li>/ul>/div>div classparagraph>p>The user manual should be published online, e.g. in Confluence. Please do not forgetto include a link to the API user manual into the API specification using thecode>#/externalDocs/url/code> property./p>/div>/div>div classsect2>h3 id103>a classlink href#103>3.4. span classmust-keyword>strong>MUST/strong>/span> write APIs using the American English language/a>/h3>/div>div classsect2>h3 id105>a classlink href#105>3.5. span classmust-keyword>strong>MUST/strong>/span> use source control for API specifications/a>/h3>div classulist>ul>li>p>We use the GitHub repository a hrefhttps://github.com/bosch-bshg-cloud/api classbare>https://github.com/bosch-bshg-cloud/api/a> for maintaining our OpenAPI specifications./p>/li>li>p>We use PRs for reviews and aligning on changes. Meta information/p>/li>/ul>/div>/div>div classsect2>h3 id218>a classlink href#218>3.6. span classmust-keyword>strong>MUST/strong>/span> contain API meta information/a>/h3>div classparagraph>p>API specifications must contain the following Open API meta informationto allow for API management:/p>/div>div classulist>ul>li>p>code>#/info/title/code> as (unique) identifying, functional descriptive name of the API/p>/li>li>p>code>#/info/version/code> to distinguish API specifications versions followinga href#116>semantic rules/a>/p>/li>li>p>code>#/info/description/code> containing a proper description of the API/p>/li>li>p>code>#/info/contact/{name,url,email}/code> containing the responsible team/p>/li>/ul>/div>/div>div classsect2>h3 id116>a classlink href#116>3.7. span classmust-keyword>strong>MUST/strong>/span> use semantic versioning/a>/h3>div classparagraph>p>Open API allows to specify the API specification version incode>#/info/version/code>. To share a common semantic of version information weexpect API designers to comply to a hrefhttp://semver.org/spec/v2.0.0.html>Semantic Versioning 2.0/a> rules code>1/code> to code>8/code> and code>11/code> restricted to the format<MAJOR>.<MINOR>.<PATCH> for versions as follows:/p>/div>div classulist>ul>li>p>Increment the strong>MAJOR/strong> version when you make incompatible API changesafter having aligned this changes with consumers,/p>/li>li>p>Increment the strong>MINOR/strong> version when you add new functionality in abackwards-compatible manner, and/p>/li>li>p>Optionally increment the strong>PATCH/strong> version when you makebackwards-compatible bug fixes or editorial changes not affecting thefunctionality./p>/li>/ul>/div>div classparagraph>p>Example:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>openapi: 3.0.1info: title: Parcel Service API description: API for <...> version: 1.3.7 <...>/code>/pre>/div>/div>/div>/div>/div>div classsect1>h2 idcompatibility>a classlink href#compatibility>4. Compatibility/a>/h2>div classsectionbody>div classsect2>h3 id106>a classlink href#106>4.1. span classmust-keyword>strong>MUST/strong>/span> not break backward compatibility/a>/h3>div classparagraph>p>Change APIs, but keep all consumers running. Consumers usually have independentrelease lifecycles, focus on stability, and avoid changes that do not provideadditional value. APIs are contracts between service providers and serviceconsumers that cannot be broken via unilateral decisions./p>/div>div classparagraph>p>There are two techniques to change APIs without breaking them:/p>/div>div classulist>ul>li>p>follow rules for compatible extensions/p>/li>li>p>introduce new API versions and still support older versions/p>/li>/ul>/div>div classparagraph>p>We strongly encourage using compatible API extensions and discourage versioning(see a href#113>span classshould-keyword>strong>SHOULD/strong>/span> avoid versioning/a>). The following guidelines for service providers(a href#107>span classshould-keyword>strong>SHOULD/strong>/span> prefer compatible extensions/a>) and consumers (a href#108>span classmust-keyword>strong>MUST/strong>/span> prepare clients accept compatible API extensions/a>) enable us (having Postel’s Law in mind) tomake compatible changes without versioning./p>/div>/div>div classsect2>h3 id107>a classlink href#107>4.2. span classshould-keyword>strong>SHOULD/strong>/span> prefer compatible extensions/a>/h3>div classparagraph>p>API designers should apply the following rules to evolve RESTful APIs forservices in a backward-compatible way:/p>/div>div classulist>ul>li>p>Add only optional, never mandatory fields./p>/li>li>p>Never change the semantic of fields (e.g. changing the semantic fromcustomer-number to customer-id, as both are different unique customer keys)/p>/li>li>p>Input fields may have (complex) constraints being validated via server-sidebusiness logic. Never change the validation logic to be more restrictive andmake sure that all constraints are clearly defined in description./p>/li>li>p>Enum ranges can be reduced when used as input parameters, only if the serveris ready to accept and handle old range values too. Enum range can be reducedwhen used as output parameters./p>/li>li>p>Enum ranges cannot be extended when used for output parameters — clients maynot be prepared to handle it. However, enum ranges can be extended when usedfor input parameters./p>/li>li>p>Use a href#112>code>x-extensible-enum/code>/a>, if range is used for output parameters and likely tobe extended with growing functionality. It defines an open list of explicitvalues and clients must be agnostic to new values./p>/li>li>p>Support redirection in case an URL has to change a href#status-code-301 classstatus-code>301/a> (Moved Permanently)./p>/li>/ul>/div>/div>div classsect2>h3 id108>a classlink href#108>4.3. span classmust-keyword>strong>MUST/strong>/span> prepare clients accept compatible API extensions/a>/h3>div classparagraph>p>Service clients should apply the robustness principle:/p>/div>div classulist>ul>li>p>Be conservative with API requests and data passed as input, e.g. avoid toexploit definition deficits like passing megabytes of strings withunspecified maximum length./p>/li>li>p>Be tolerant in processing and reading data of API responses, morespecifically…/p>/li>/ul>/div>div classparagraph>p>Service clients must be prepared for compatible API extensions of serviceproviders:/p>/div>div classulist>ul>li>p>Be tolerant with unknown fields in the payload (see also Fowler’sa hrefhttp://martinfowler.com/bliki/TolerantReader.html>TolerantReader/a> post),i.e. ignore new fields but do not eliminate them from payload if needed forsubsequent a href#put>code>PUT/code>/a> requests./p>/li>li>p>Be prepared that a href#112>code>x-extensible-enum/code>/a> return parameter may deliver new values;either be agnostic or provide default behavior for unknown values./p>/li>li>p>Be prepared to handle HTTP status codes not explicitly specified in endpointdefinitions. Note also, that status codes are extensible. Default handling ishow you would treat the corresponding a href#http-status-codes-and-errors classstatus-code>2xx/a> code (seea hrefhttps://tools.ietf.org/html/rfc7231#section-6>RFC 7231 Section 6/a>)./p>/li>li>p>Follow the redirect when the server returns HTTP status code a href#status-code-301 classstatus-code>301/a> (MovedPermanently)./p>/li>/ul>/div>/div>div classsect2>h3 id109>a classlink href#109>4.4. span classshould-keyword>strong>SHOULD/strong>/span> design APIs conservatively/a>/h3>div classparagraph>p>Designers of service provider APIs should be conservative and accurate in whatthey accept from clients:/p>/div>div classulist>ul>li>p>Unknown input fields in payload or URL should not be ignored; servers shouldprovide error feedback to clients via an HTTP 400 response code./p>/li>li>p>Be accurate in defining input data constraints (like formats, ranges, lengthsetc.) — and check constraints and return dedicated error information in caseof violations./p>/li>li>p>Prefer being more specific and restrictive (if compliant to functionalrequirements), e.g. by defining length range of strings. It may simplifyimplementation while providing freedom for further evolution as compatibleextensions./p>/li>/ul>/div>/div>div classsect2>h3 id110>a classlink href#110>4.5. span classmust-keyword>strong>MUST/strong>/span> always return JSON objects as top-level data structures/a>/h3>div classparagraph>p>In a response body, you must always return a JSON object (and not e.g. anarray) as a top level data structure to support future extensibility. JSONobjects support compatible extension by additional attributes. This allows youto easily extend your response and e.g. add pagination later, without breakingbackwards compatibility./p>/div>div classparagraph>p>Maps (see a href#216>span classshould-keyword>strong>SHOULD/strong>/span> define maps using code>additionalProperties/code>/a>), even though technically objects, are also forbidden as toplevel data structures, since they don’t support compatible, future extensions./p>/div>/div>div classsect2>h3 id112>a classlink href#112>4.6. span classshould-keyword>strong>SHOULD/strong>/span> used open-ended list of values (code>x-extensible-enum/code>) for enumerations/a>/h3>div classparagraph>p>Enumerations are per definition closed sets of values, that are assumed to becomplete and not intended for extension. This closed principle of enumerationsimposes compatibility issues when an enumeration must be extended. To avoidthese issues, we strongly recommend to use an open-ended list of values insteadof an enumeration unless:/p>/div>div classolist arabic>ol classarabic>li>p>the API has full control of the enumeration values, i.e. the list of valuesdoes not depend on any external tool or interface, and/p>/li>li>p>the list of value is complete with respect to any thinkable and unthinkablefuture feature./p>/li>/ol>/div>div classparagraph>p>To specify an open-ended list of values use the marker a href#112>code>x-extensible-enum/code>/a> asfollows:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>deliveryMethods: type: string x-extensible-enum: - PARCEL - LETTER - EMAIL/code>/pre>/div>/div>div classparagraph>p>strong>Note:/strong> a href#112>code>x-extensible-enum/code>/a> is not JSON Schema conform but will be ignored bymost tools./p>/div>div classparagraph>p>See a href#240>span classshould-keyword>strong>SHOULD/strong>/span> declare enum values using UPPER_SNAKE_CASE format/a> about enum value naming conventions./p>/div>/div>div classsect2>h3 id113>a classlink href#113>4.7. span classshould-keyword>strong>SHOULD/strong>/span> avoid versioning/a>/h3>div classparagraph>p>When changing your RESTful APIs, do so in a compatible way and avoid generatingadditional API versions (see a href#115>span classmust-keyword>strong>MUST/strong>/span> use URI versioning/a>). Multiple versions can significantly complicateunderstanding, testing, maintaining, evolving, operating and releasing oursystems(a hrefhttp://martinfowler.com/articles/enterpriseREST.html>supplementaryreading/a>)./p>/div>/div>div classsect2>h3 id115>a classlink href#115>4.8. span classmust-keyword>strong>MUST/strong>/span> use URI versioning/a>/h3>div classparagraph>p>With URI versioning a (major) version number is included as the first element in the path, e.g.code>/v1/customers/code>./p>/div>div classparagraph>p>strong>Important/strong>: Even with the mechanism of URI versioning in place, creating new major versions should be avoided whenever possible (see a href#113>span classshould-keyword>strong>SHOULD/strong>/span> avoid versioning/a>). If a new major version is not avoidable and changes must be done in a non backwards compatible way, URI versioning must be used./p>/div>div classparagraph>p>Whenever a new major version is created the previous one must be declared deprecated and the end of life date must be communicated so all consumers can upgrade to the new version in a timely manner./p>/div>div classparagraph>p>strong>Note/strong>: Even so some other guidelines (including the Zalando Guidelines) advocate for the use of Media Type Versioning, we decided against that approach for the following reasons/p>/div>div classulist>ul>li>p>Custom media types instead of code>application/json/code> are not supported by all clients/p>/li>li>p>Custom media types are more complicated to implement/p>/li>li>p>We do not generally recommend to implement REST Maturity Level 3 (see a href#163>span classmay-keyword>strong>MAY/strong>/span> use REST maturity level 3 - HATEOAS/a>) so hypermedia links are not a problem./p>/li>/ul>/div>/div>/div>/div>div classsect1>h2 iddeprecation>a classlink href#deprecation>5. Deprecation/a>/h2>div classsectionbody>div classparagraph>p>Sometimes it is necessary to phase out an API endpoint, an API version, or anAPI feature, e.g. if a field or parameter is no longer supported or a wholebusiness functionality behind an endpoint is supposed to be shut down. As longas the API endpoints and features are still used by consumers these shut downsare breaking changes and not allowed. To progress the following deprecationrules have to be applied to make sure that the necessary consumer changes andactions are well communicated and aligned using em>deprecation/em> and em>sunset/em>dates./p>/div>div classsect2>h3 id185>a classlink href#185>5.1. span classmust-keyword>strong>MUST/strong>/span> obtain approval of clients before API shut down/a>/h3>div classparagraph>p>Before shutting down an API, version of an API, or API feature the producermust make sure, that all clients have given their consent on a sunset date.Producers should help consumers to migrate to a potential new API or APIfeature by providing a migration manual and clearly state the time line forreplacement availability and sunset. Once all clients ofa sunset API feature are migrated, the producer may shut down the deprecatedAPI feature./p>/div>/div>div classsect2>h3 id186>a classlink href#186>5.2. span classmust-keyword>strong>MUST/strong>/span> collect external partner consent on deprecation time span/a>/h3>div classparagraph>p>If the API is consumed by any external partner, the API owner must define areasonable time span that the API will be maintained after the producer hasannounced deprecation. All external partners must state consent with thisafter-deprecation-life-span, i.e. the minimum time span between officialdeprecation and first possible sunset, strong>before/strong> they are allowed to use theAPI./p>/div>/div>div classsect2>h3 id187>a classlink href#187>5.3. span classmust-keyword>strong>MUST/strong>/span> reflect deprecation in API specifications/a>/h3>div classparagraph>p>The API deprecation must be part of the API specification./p>/div>div classparagraph>p>If an API endpoint (operation object), an input argument (parameter object),an in/out data object (schema object), or on a more fine grained level, aschema attribute or property should be deprecated, the producers must setcode>deprecated: true/code> for the affected element and add further explanation to thecode>description/code> section of the API specification. If a future shut down isplanned, the producer must provide a sunset date and document in detailswhat consumers should use instead and how to migrate./p>/div>/div>div classsect2>h3 id188>a classlink href#188>5.4. span classmust-keyword>strong>MUST/strong>/span> monitor usage of deprecated API scheduled for sunset/a>/h3>div classparagraph>p>Owners of an API, API version, or API feature used in production that isscheduled for sunset must monitor the usage of the sunset API, API version, orAPI feature in order to observe migration progress and avoid uncontrolledbreaking effects on ongoing consumers./p>/div>/div>div classsect2>h3 id191>a classlink href#191>5.5. span classmust-keyword>strong>MUST/strong>/span> not start using deprecated APIs/a>/h3>div classparagraph>p>Clients must not start using deprecated APIs, API versions, or API features./p>/div>/div>/div>/div>div classsect1>h2 idjson-guidelines>a classlink href#json-guidelines>6. JSON guidelines/a>/h2>div classsectionbody>div classparagraph>p>These guidelines provides recommendations for defining JSON data.JSON here refers to a hrefhttps://tools.ietf.org/html/rfc7159>RFC 7159/a> (which updates a hrefhttps://tools.ietf.org/html/rfc4627>RFC 4627/a>),the application/json media type and custom JSON media types defined for APIs./p>/div>div classparagraph>p>The first some of the following guidelines are about property names, the laterones about values./p>/div>div classsect2>h3 id118>a classlink href#118>6.1. span classmust-keyword>strong>MUST/strong>/span> property names must be alphanumeric ASCII camelCase/a>/h3>div classparagraph>p>Property names are restricted to alphanumeric ASCII strings (incl. code>_/code> as a first character) in lowercamelCase format (a hrefhttps://en.wikipedia.org/wiki/Camel_case classbare>https://en.wikipedia.org/wiki/Camel_case/a>)./p>/div>div classparagraph>p>Rationale: It’s essential to establish a consistent look and feel such that JSON looks as if it came from the same hand./p>/div>/div>div classsect2>h3 id240>a classlink href#240>6.2. span classshould-keyword>strong>SHOULD/strong>/span> declare enum values using UPPER_SNAKE_CASE format/a>/h3>div classparagraph>p>Enum values (using code>enum/code> or a href#112>code>x-extensible-enum/code>/a>) need to consistently use the upper-snake case format, e.g. code>VALUE/code> or code>YET_ANOTHER_VALUE/code>. This approach allows to clearly distinguish values from properties or other elements./p>/div>div classparagraph>p>strong>Note:/strong> This does not apply where the actual exact values are coming from some outside source, e.g. for language codes from a hrefhttps://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>ISO 639-1/a>, or when declaring possible values for a #137code>sort/code> parameter./p>/div>/div>div classsect2>h3 id216>a classlink href#216>6.3. span classshould-keyword>strong>SHOULD/strong>/span> define maps using code>additionalProperties/code>/a>/h3>div classparagraph>p>A map here is a mapping from string keys to some other type. In JSON this isrepresented as an object, the key-value pairs being represented by propertynames and property values. In Open API schema (as well as in JSON schema) theyshould be represented using additionalProperties with a schema defining thevalue type. Such an object should normally have no other defined properties./p>/div>div classparagraph>p>The map keys don’t count as property names in the sense of a href#118>rule 118/a>,and can follow whatever format is natural for their domain. Please documentthis in the description of the map object’s schema./p>/div>div classparagraph>p>Here is an example for such a map definition (the code>translations/code> property):/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>components: schemas: Message: description: A message together with translations in several languages. type: object properties: messageKey: type: string description: The message key. translations: description: The translations of this message into several languages. The keys are IETF BCP-47 language tags(https://tools.ietf.org/html/bcp47). type: object additionalProperties: type: string description: the translation of this message into the language identified by the key./code>/pre>/div>/div>div classparagraph>p>An actual JSON object described by this might then look like this:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-json hljs data-langjson>{ messageKey: color, translations: { de: Farbe, en-US: color, en-GB: colour, eo: koloro, nl: kleur }}/code>/pre>/div>/div>/div>div classsect2>h3 id120>a classlink href#120>6.4. span classshould-keyword>strong>SHOULD/strong>/span> pluralize array names/a>/h3>div classparagraph>p>To indicate they contain multiple values prefer to pluralize arraynames. This implies that object names should in turn be singular./p>/div>/div>div classsect2>h3 id122>a classlink href#122>6.5. span classmust-keyword>strong>MUST/strong>/span> not use code>null/code> for boolean properties/a>/h3>div classparagraph>p>Schema based JSON properties that are by design booleans must not bepresented as nulls. A boolean is essentially a closed enumeration of twovalues, true and false. If the content has a meaningful null value,strongly prefer to replace the boolean with enumeration of named valuesor statuses - for example accepted_terms_and_conditions with true orfalse can be replaced with terms_and_conditions with values yes, no andunknown./p>/div>/div>div classsect2>h3 id123>a classlink href#123>6.6. span classmust-keyword>strong>MUST/strong>/span> use same semantics for code>null/code> and absent properties/a>/h3>div classparagraph>p>Open API 3.x allows to mark properties as code>required/code> and as code>nullable/code> tospecify whether properties may be absent (code>{}/code>) or code>null/code> (code>{example:null}/code>).If a property is defined to be not code>required/code> and code>nullable/code>, this rule demandsthat both cases must be handled in the exact same manner by specification./p>/div>div classparagraph>p>While API designers and implementers may be tempted to assign differentsemantics to both cases, we explicitly decide strong>against/strong> that option, because wethink that any gain in expressiveness is far outweighed by the risk of clientsnot understanding and implementing the subtle differences incorrectly./p>/div>div classparagraph>p>Moreover, many major libraries have somewhere between little to no support fora code>null/code>/absent pattern (seea hrefhttps://stackoverflow.com/questions/48465005/gson-distinguish-null-value-field-and-missing-field>Gson/a>,a hrefhttps://github.com/square/moshi#borrows-from-gson>Moshi/a>,a hrefhttps://github.com/FasterXML/jackson-databind/issues/578>Jackson/a>,a hrefhttps://developer.ibm.com/articles/j-javaee8-json-binding-3/>JSON-B/a>). Especiallystrongly-typed languages suffer from this since a new composite type is requiredto express the third state. Nullable code>Option/code>/code>Optional/code>/code>Maybe/code> types could beused but having nullable references of these types completely contradicts theirpurpose./p>/div>div classparagraph>p>The only exception to this rule is JSON Merge Patch a hrefhttps://tools.ietf.org/html/rfc7396>RFC 7396/a>) whichuses code>null/code> to explicitly indicate property deletion while absent properties areignored, i.e. not modified./p>/div>/div>div classsect2>h3 id124>a classlink href#124>6.7. span classmust-keyword>strong>MUST/strong>/span> not use code>null/code> for empty arrays/a>/h3>div classparagraph>p>Empty array values can unambiguously be represented as the empty list, code>/code>./p>/div>/div>div classsect2>h3 id235>a classlink href#235>6.8. span classshould-keyword>strong>SHOULD/strong>/span> name date/time properties with code>Date/code> suffix/a>/h3>div classparagraph>p>Dates and date-time properties should end with code>Date/code> to distinguish them fromboolean properties which otherwise would have very similar or even identicalnames:/p>/div>div classulist>ul>li>p>code>creationDate/code> rather than code>created/code>,/p>/li>li>p>code>modifiedDate/code> rather than code>modified/code>,/p>/li>li>p>code>occurrenceDate/code> rather than code>occurred/code>, and/p>/li>li>p>code>returnDate/code> rather than code>returned/code>./p>/li>/ul>/div>/div>div classsect2>h3 id126>a classlink href#126>6.9. span classshould-keyword>strong>SHOULD/strong>/span> define dates properties compliant with RFC 3339/a>/h3>div classparagraph>p>Use the date and time formats defined by a hrefhttps://tools.ietf.org/html/rfc3339#section-5.6>RFC 3339/a>./p>/div>div classparagraph>p>Do strong>not/strong> use whitespaces between the date and the time segments. Always use the code>T/code>./p>/div>div classsect3>h4 iddate>a classlink href#date>6.9.1. Date/a>/h4>div classparagraph>p>For date use strings matching code>date-fullyear - date-month - date-mday/code>/p>/div>div classparagraph>p>Examples:/p>/div>div classulist>ul>li>p>code>2015-01-01/code>/p>/li>li>p>code>2015-05-28/code>/p>/li>li>p>code>2000-12-31/code>/p>/li>/ul>/div>/div>div classsect3>h4 iddatetime>a classlink href#datetime>6.9.2. DateTime/a>/h4>div classparagraph>p>For date-time use strings matching code>full-date T full-time/code>/p>/div>div classparagraph>p>Examples:/p>/div>div classulist>ul>li>p>code>2015-05-28T14:07:17Z/code>/p>/li>li>p>code>1990-12-31T15:59:60-08:00/code>/p>/li>li>p>code>1937-01-01T12:00:27.87+00:20/code>/p>/li>/ul>/div>/div>/div>div classsect2>h3 id127>a classlink href#127>6.10. span classshould-keyword>strong>SHOULD/strong>/span> define time durations and intervals properties conform to ISO 8601/a>/h3>div classparagraph>p>Schema based JSON properties that are by design durations and intervals couldbe strings formatted as recommended by a hrefhttps://en.wikipedia.org/wiki/ISO_8601>ISO 8601/a>(a hrefhttps://tools.ietf.org/html/rfc3339#appendix-A>Appendix A of RFC 3339 contains a grammar/a> for durations)./p>/div>/div>/div>/div>div classsect1>h2 iddata-formats>a classlink href#data-formats>7. Data formats/a>/h2>div classsectionbody>div classsect2>h3 id167>a classlink href#167>7.1. span classmust-keyword>strong>MUST/strong>/span> use JSON as payload data interchange format/a>/h3>div classparagraph>p>Use JSON (a hrefhttps://tools.ietf.org/html/rfc7159>RFC 7159/a>) to represent structured (resource) datapassed with HTTP requests and responses as body payload.The JSON payload must use a JSON object as top-level datastructure (if possible) to allow for future extension. This also applies tocollection resources, where you ad-hoc would use an array — see alsoa href#110>span classmust-keyword>strong>MUST/strong>/span> always return JSON objects as top-level data structures/a>./p>/div>div classparagraph>p>Additionally, the JSON payload must comply to the more restrictive Internet JSON (a hrefhttps://tools.ietf.org/html/rfc7493>RFC 7493/a>),particularly/p>/div>div classulist>ul>li>p>a hrefhttps://tools.ietf.org/html/rfc7493#section-2.1>Section 2.1/a> on encoding of characters, and/p>/li>li>p>a hrefhttps://tools.ietf.org/html/rfc7493#section-2.3>Section 2.3/a> on object constraints./p>/li>/ul>/div>div classparagraph>p>As a consequence, a JSON payload must/p>/div>div classulist>ul>li>p>use a hrefhttps://tools.ietf.org/html/rfc7493#section-2.1>code>UTF-8/code> encoding/a>/p>/li>li>p>consist of a hrefhttps://tools.ietf.org/html/rfc7493#section-2.1>valid Unicode strings/a>, i.e. must notcontain non-characters or surrogates, and/p>/li>li>p>contain only a hrefhttps://tools.ietf.org/html/rfc7493#section-2.3>unique member names/a> (no duplicatenames)./p>/li>/ul>/div>/div>div classsect2>h3 id172>a classlink href#172>7.2. span classshould-keyword>strong>SHOULD/strong>/span> prefer standard media type name code>application/json/code>/a>/h3>div classparagraph>p>Use the standard media type namecode>application/json/code> (or code>application/problem+json/code> for a href#176>span classmust-keyword>strong>MUST/strong>/span> support problem JSON/a>)as content type (or accept header) information for JSON payload./p>/div>/div>div classsect2>h3 id168>a classlink href#168>7.3. span classmay-keyword>strong>MAY/strong>/span> pass non-JSON media types using data specific standard formats/a>/h3>div classparagraph>p>Non-JSON media types may be supported, if you stick to a business object specific standardformat for the payload data, for instance, image data format (JPG, PNG, GIF), documentformat (PDF, DOC, ODF, PPT), or archive format (TAR, ZIP)./p>/div>div classparagraph>p>Generic structured data interchange formats other than JSON (e.g. XML, CSV)may be provided, but only additionally to JSON as default format using content negotiation,for specific use cases where clients may not interpret the payload structure./p>/div>div classsect3>h4 id239>a classlink href#239>7.3.1. span classshould-keyword>strong>SHOULD/strong>/span> encode embedded binary data in code>base64url/code>/a>/h4>div classparagraph>p>Exposing binary data using an alternative media type is generally preferred.See a href#168>the rule above/a>./p>/div>div classparagraph>p>If an alternative content representation is not desired then binary data shouldbe embedded into the JSON document as a code>base64url/code>-encoded string propertyfollowing a hrefhttps://tools.ietf.org/html/rfc7493#section-4.4>RFC 7493 Section 4.4/a>./p>/div>/div>/div>div classsect2>h3 id238>a classlink href#238>7.4. span classshould-keyword>strong>SHOULD/strong>/span> use standardized property formats/a>/h3>div classparagraph>p>a hrefhttps://json-schema.org/understanding-json-schema/reference/string.html#format>JSON Schema/a>and a hrefhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types>Open API/a>define several data formats, e.g. code>date/code>, code>time/code>, code>email/code>, and code>url/code>, based on ISO and IETF standards.The following table lists these formats including additional formats useful in an e-commerce environment.You strong>should/strong> use these formats, whenever applicable./p>/div>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 10%;>col stylewidth: 25%;>col stylewidth: 25%;>col stylewidth: 40%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>code>type/code>/th>th classtableblock halign-left valign-top>code>format/code>/th>th classtableblock halign-left valign-top>Specification/th>th classtableblock halign-left valign-top>Example/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>code>integer/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#171>code>int32/code>/a>/p>/td>td classtableblock halign-left valign-top>/td>td classtableblock halign-left valign-top>p classtableblock>code>7721071004/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>integer/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#171>code>int64/code>/a>/p>/td>td classtableblock halign-left valign-top>/td>td classtableblock halign-left valign-top>p classtableblock>code>772107100456824/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>integer/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#171>code>bigint/code>/a>/p>/td>td classtableblock halign-left valign-top>/td>td classtableblock halign-left valign-top>p classtableblock>code>77210710045682438959/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>number/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#171>code>float/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/IEEE_754>IEEE 754-2008/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>3.1415927/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>number/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#171>code>double/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/IEEE_754>IEEE 754-2008/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>3.141592653589793/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>number/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#171>code>decimal/code>/a>/p>/td>td classtableblock halign-left valign-top>/td>td classtableblock halign-left valign-top>p classtableblock>code>3.141592653589793238462643383279/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#170>code>bcp47/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/bcp47>BCP 47/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>en-DE/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>byte/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc7493>RFC 7493/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>dGVzdA/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#126>code>date/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc3339>RFC 3339/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>2019-07-30/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#126>code>date-time/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc3339>RFC 3339/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>2019-07-30T06:43:40.252Z/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>email/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc5322>RFC 5322/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>a hrefmailto:example@bosch-home.com>example@bosch-home.com/a>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>gtin-13/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/Global_Trade_Item_Number>GTIN/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>5710798389878/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>hostname/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc1034>RFC 1034/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>bosch-home.com/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>ipv4/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc2673>RFC 2673/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>104.75.173.179/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>ipv6/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc2673>RFC 2673/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>2600:1401:2::8a/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#170>code>iso-3166/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>ISO 3166-1 alpha-2/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>DE/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#173>code>iso-4217/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/ISO_4217>ISO 4217/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>EUR/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#170>code>iso-639/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>ISO 639-1/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>de/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>json-pointer/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc6901>RFC 6901/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>/items/0/id/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>password/code>/p>/td>td classtableblock halign-left valign-top>/td>td classtableblock halign-left valign-top>p classtableblock>code>secret/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>regex/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttp://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf>ECMA 262/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>^a-z0-9+$/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#126>code>time/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc3339>RFC 3339/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>06:43:40.252Z/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>uri/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc3986>RFC 3986/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>https://www.bosch-home.com//code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>uri-template/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc6570>RFC 6570/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>/users/{id}/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>code>string/code>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#144>code>uuid/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://tools.ietf.org/html/rfc4122>RFC 4122/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>code>e2ab873e-b295-11e9-9c02-…/code>/p>/td>/tr>/tbody>/table>div classparagraph>p>strong>Remark:/strong> Please note that this list of standard data formats is not exhaustiveand everyone is encouraged to propose additions./p>/div>/div>div classsect2>h3 id170>a classlink href#170>7.5. span classshould-keyword>strong>SHOULD/strong>/span> use standards for country, language and currency codes/a>/h3>div classparagraph>p>Use the following standard formats for country, language and currencycodes:/p>/div>div classulist>ul>li>p>Country codes: a hrefhttps://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>ISO 3166-1-alpha2/a> two letter country codes/p>/li>li>p>Language codes: a hrefhttps://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>ISO 639-1/a> two letter language codes/p>/li>li>p>Currency codes: a hrefhttps://en.wikipedia.org/wiki/ISO_4217>ISO 4217/a> three letter currency codes/p>/li>/ul>/div>/div>div classsect2>h3 id171>a classlink href#171>7.6. span classmust-keyword>strong>MUST/strong>/span> define format for number and integer types/a>/h3>div classparagraph>p>Whenever an API defines a property of type code>number/code> or code>integer/code>, theprecision must be defined by the format as follows to prevent clientsfrom guessing the precision incorrectly, and thereby changing the valueunintentionally:/p>/div>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 15%;>col stylewidth: 15%;>col stylewidth: 70%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>type/th>th classtableblock halign-left valign-top>format/th>th classtableblock halign-left valign-top>specified value range/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>integer/p>/td>td classtableblock halign-left valign-top>p classtableblock>int32/p>/td>td classtableblock halign-left valign-top>p classtableblock>integer between -2sup>31/sup> and 2sup>31/sup>-1/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>integer/p>/td>td classtableblock halign-left valign-top>p classtableblock>int64/p>/td>td classtableblock halign-left valign-top>p classtableblock>integer between -2sup>63/sup> and 2sup>63/sup>-1/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>integer/p>/td>td classtableblock halign-left valign-top>p classtableblock>bigint/p>/td>td classtableblock halign-left valign-top>p classtableblock>arbitrarily large signed integer number/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>number/p>/td>td classtableblock halign-left valign-top>p classtableblock>float/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/IEEE_754>IEEE 754-2008/ISO 60559:2011/a> binary32 decimal number/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>number/p>/td>td classtableblock halign-left valign-top>p classtableblock>double/p>/td>td classtableblock halign-left valign-top>p classtableblock>a hrefhttps://en.wikipedia.org/wiki/IEEE_754>IEEE 754-2008/ISO 60559:2011/a> binary64 decimal number/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>number/p>/td>td classtableblock halign-left valign-top>p classtableblock>decimal/p>/td>td classtableblock halign-left valign-top>p classtableblock>arbitrarily precise signed decimal number/p>/td>/tr>/tbody>/table>div classparagraph>p>The precision must be translated by clients and servers into the mostspecific language types. E.g. for the following definitions the mostspecific language types in Java will translate to code>BigDecimal/code> forcode>Money.amount/code> and code>int/code> or code>Integer/code> for the code>OrderList.pageSize/code>:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>components: schemas: Money: type: object properties: amount: type: number description: Amount expressed as a decimal number of major currency units format: decimal example: 99.95 ... OrderList: type: object properties: pageSize: type: integer description: Number of orders in list format: int32 example: 42/code>/pre>/div>/div>/div>/div>/div>div classsect1>h2 idcommon-data-types>a classlink href#common-data-types>8. Common data types/a>/h2>div classsectionbody>div classparagraph>p>Definitions of data objects that are good candidates for wider usage. Below you can find a list of common data typesused in the guideline:/p>/div>div classulist>ul>li>p>a href#173>Money object/a>/p>/li>li>p>a href#176>Problem object/a>/p>/li>/ul>/div>div classsect2>h3 id173>a classlink href#173>8.1. span classmust-keyword>strong>MUST/strong>/span> use the common money object/a>/h3>div classparagraph>p>Use the following common money structure:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>Money: type: object properties: amount: type: number description: > The amount describes unit and subunit of the currency in a single value, where the integer part (digits before the decimal point) is for the major unit and fractional part (digits after the decimal point) is for the minor unit. format: float example: 99.95 currency: type: string description: 3 letter currency code as defined by ISO-4217 format: iso-4217 example: EUR required: - amount - currency/code>/pre>/div>/div>div classparagraph>p>Please note that APIs have to treat Money as a closed data type, i.e. it’s not meant to be used in an inheritance hierarchy. That means the following usage is not allowed:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-json hljs data-langjson>{ amount: 19.99, currency: EUR, discountedAmount: 9.99}/code>/pre>/div>/div>/div>div classsect2>h3 id174>a classlink href#174>8.2. span classmust-keyword>strong>MUST/strong>/span> use common field names and semantics/a>/h3>div classparagraph>p>There exist a variety of field types that are required in multiple places. Toachieve consistency across all API implementations, you must use common fieldnames and semantics whenever applicable./p>/div>div classsect3>h4 idgeneric-fields>a classlink href#generic-fields>8.2.1. Generic fields/a>/h4>div classparagraph>p>There are some data fields that come up again and again in API data:/p>/div>div classulist>ul>li>p>a idid>/a>a href#id>code>id/code>/a>: the identity of the object. If used, IDs must be opaque stringsand not numbers. IDs are unique within some documented context, are stableand don’t change for a given object once assigned, and are never recycledcross entities./p>/li>li>p>a idxyzId>/a>{xyzId}: an attribute within one object holding the identifier ofanother object must use a name that corresponds to the type of the referencedobject or the relationship to the referenced object followed by code>Id/code> (e.g.code>partnerId/code> not code>partnerNumber/code>, or code>parentNodeId/code> for the reference to a parentnode from a child node, even if both have the type code>Node/code>)./p>/li>li>p>a idcreationDate>/a>{creationDate}: when the object was created. If used, this mustbe a code>date-time/code> construct.adding the a href#235>naming conventions for date/time properties/a>./p>/li>li>p>a idmodificationDate>/a>{modificationDate}: when the object was updated. If used, this mustbe a code>date-time/code> construct.adding the a href#235>naming conventions for date/time properties/a>./p>/li>li>p>a idtype>/a>a href#type>code>type/code>/a>: the kind of thing this object is. If used, the type of thisfield should be a string. Types allow runtime information on the entityprovided that otherwise requires examining the Open API file./p>/li>/ul>/div>div classparagraph>p>Example JSON schema:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>treeNode: type: object properties: id: description: the identifier of this node type: string createdAt: description: when got this node created type: string format: date-time modifiedAt: description: when got this node last updated type: string format: date-time type: type: string enum: LEAF, NODE parentNodeId: description: the identifier of the parent node of this node type: string example: id: 123435 createdAt: 2017-04-12T23:20:50.52Z modifiedAt: 2017-04-12T23:20:50.52Z type: LEAF parentNodeId: 534321/code>/pre>/div>/div>div classparagraph>p>These properties are not always strictly necessary, but making them idiomaticallows API client developers to build up a common understanding. There is very little utility for API consumers in having differentnames or value types for these fields across APIs./p>/div>/div>/div>/div>/div>div classsect1>h2 idapi-naming>a classlink href#api-naming>9. API naming/a>/h2>div classsectionbody>div classsect2>h3 id129>a classlink href#129>9.1. span classmust-keyword>strong>MUST/strong>/span> use lowercase separate words with hyphens for path segments/a>/h3>div classparagraph>p>Example:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/shipment-orders/{shipment-order-id}/code>/pre>/div>/div>div classparagraph>p>This applies to concrete path segments and not the names of pathparameters. For example code>{shipment_order_id}/code> would be ok as a pathparameter./p>/div>/div>div classsect2>h3 id130>a classlink href#130>9.2. span classmust-keyword>strong>MUST/strong>/span> use snake_case (never camelCase) for query parameters/a>/h3>div classparagraph>p>Examples:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-none hljs>customer_number, order_id, billing_address/code>/pre>/div>/div>/div>div classsect2>h3 id132>a classlink href#132>9.3. span classshould-keyword>strong>SHOULD/strong>/span> prefer hyphenated-pascal-case for HTTP header fields/a>/h3>div classparagraph>p>This is for consistency in your documentation (most other headers followthis convention). Avoid camelCase (without hyphens). Exceptions arecommon abbreviations like ID./p>/div>div classparagraph>p>Examples:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>Accept-EncodingApply-To-Redirect-RefDisposition-Notification-OptionsOriginal-Message-ID/code>/pre>/div>/div>div classparagraph>p>See also: a hrefhttps://tools.ietf.org/html/rfc7230#page-22>HTTP Headers are case-insensitive (RFC 7230)/a>./p>/div>div classparagraph>p>See a href#proprietary-headers>Proprietary headers/a> sections for more guidanceon HTTP headers./p>/div>/div>div classsect2>h3 id134>a classlink href#134>9.4. span classmust-keyword>strong>MUST/strong>/span> pluralize resource names/a>/h3>div classparagraph>p>Usually, a collection of resource instances is provided (at least the APIshould be ready here). The special case of a em>resource singleton/em> mustbe modeled as a collection with cardinality 1 including definition ofcode>maxItems/code> code>minItems/code> 1 for the returned code>array/code> structureto make the cardinality constraint explicit./p>/div>div classparagraph>p>strong>Exception:/strong> the em>pseudo identifier/em> code>self/code> used to specify a resource endpointwhere the resource identifier is provided by authorization information (see a href#143>span classmust-keyword>strong>MUST/strong>/span> identify resources and sub-resources via path segments/a>)./p>/div>/div>div classsect2>h3 id137>a classlink href#137>9.5. span classmust-keyword>strong>MUST/strong>/span> stick to conventional query parameters/a>/h3>div classparagraph>p>If you provide query support for searching, sorting, filtering, andpaginating, you must stick to the following naming conventions:/p>/div>div classulist>ul>li>p>a idq>/a>a href#q>code>q/code>/a>: default query parameter, e.g. used by browser tab completion;should have an entity specific alias, e.g. sku./p>/li>li>p>a idsort>/a>a href#sort>code>sort/code>/a>: comma-separated list of fields todefine the sort order. To indicate sorting direction, fields may be prefixedwith code>+/code> (ascending) or code>-/code> (descending), e.g. /sales-orders?sort+id./p>/li>li>p>a idembed>/a>a href#embed>code>embed/code>/a>: field name expression to expand or embedded sub-entities,e.g. inside of an article entity, expand silhouette code into the silhouetteobject. Implementing a href#embed>code>embed/code>/a> correctly is difficult, so do it with care.See a href#158>span classshould-keyword>strong>SHOULD/strong>/span> allow optional embedding of sub-resources/a> below./p>/li>li>p>a idoffset>/a>a href#offset>code>offset/code>/a>: numeric offset of the first element provided on a pagerepresenting a collection request./p>/li>li>p>a idlimit>/a>a href#limit>code>limit/code>/a>: client suggested limit to restrict the number of entries ona page./p>/li>/ul>/div>/div>/div>/div>div classsect1>h2 idresources>a classlink href#resources>10. Resources/a>/h2>div classsectionbody>div classsect2>h3 id138>a classlink href#138>10.1. span classmust-keyword>strong>MUST/strong>/span> avoid actions - think about resources/a>/h3>div classparagraph>p>REST is all about your resources, so consider the domain entities that takepart in web service interaction, and aim to model your API around these usingthe standard HTTP methods as operation indicators. For instance, if anapplication has to lock articles explicitly so that only one user may editthem, create an article lock with a href#put>code>PUT/code>/a> or a href#post>code>POST/code>/a> instead of using a lockaction./p>/div>div classparagraph>p>Request:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>PUT /article-locks/{article-id}/code>/pre>/div>/div>div classparagraph>p>The added benefit is that you already have a service for browsing and filteringarticle locks./p>/div>/div>div classsect2>h3 id140>a classlink href#140>10.2. span classshould-keyword>strong>SHOULD/strong>/span> define em>useful/em> resources/a>/h3>div classparagraph>p>As a rule of thumb resources should be defined to cover 90% of all its client’suse cases. A em>useful/em> resource should contain as much information as necessary,but as little as possible. A great way to support the last 10% is to allowclients to specify their needs for more/less information by supportingfiltering and embedding./p>/div>/div>div classsect2>h3 id141>a classlink href#141>10.3. span classmust-keyword>strong>MUST/strong>/span> keep URLs verb-free/a>/h3>div classparagraph>p>The API describes resources, so the only place where actions should appear isin the HTTP methods. In URLs, use only nouns. Instead of thinking of actions(verbs), it’s often helpful to think about putting a message in a letter box:e.g., instead of having the verb em>cancel/em> in the url, think of sending amessage to cancel an order to the em>cancellations/em> letter box on the serverside./p>/div>/div>div classsect2>h3 id142>a classlink href#142>10.4. span classmust-keyword>strong>MUST/strong>/span> use domain-specific resource names/a>/h3>div classparagraph>p>API resources represent elements of the application’s domain model. Usingdomain-specific nomenclature for resource names helps developers to understandthe functionality and basic semantics of your resources. It also reduces theneed for further documentation outside the API definition. For example,sales-order-items is superior to order-items in that it clearly indicateswhich business object it represents. Along these lines, items is too general./p>/div>/div>div classsect2>h3 id228>a classlink href#228>10.5. span classmust-keyword>strong>MUST/strong>/span> use URL-friendly resource identifiers: a-zA-Z0-9:._\-/*/a>/h3>div classparagraph>p>To simplify encoding of resource IDs in URLs, their representation must onlyconsist of ASCII strings using letters, numbers, underscore, minus, colon,period, and - on rare occasions - slash./p>/div>div classparagraph>p>strong>Note:/strong> slashes are only allowed to build and signal resource identifiersconsisting of a href#241>compound keys/a>./p>/div>div classparagraph>p>strong>Note:/strong> to prevent ambiguities of unnormalized paths resourceidentifiers must never be empty. Consequently, support of empty strings forpath parameters is forbidden./p>/div>/div>div classsect2>h3 id143>a classlink href#143>10.6. span classmust-keyword>strong>MUST/strong>/span> identify resources and sub-resources via path segments/a>/h3>div classparagraph>p>Some API resources may contain or reference sub-resources. Embeddedsub-resources, which are not top-level resources, are parts of a higher-levelresource and cannot be used outside of its scope. Sub-resources should bereferenced by their name and identifier in the path segments as follows:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/resources/{resource-id}/sub-resources/{sub-resource-id}/code>/pre>/div>/div>div classparagraph>p>In order to improve the consumer experience, you should aim for intuitivelyunderstandable URLs, where each sub-path is a valid reference to a resource ora set of resources. For instance, if code>/partners/{partner-id}/addresses/{address-id}/code> is valid,then, in principle, also code>/partners/{partner-id}/addresses/code>, code>/partners/{partner-id}/code> andcode>/partners/code> must be valid. Examples of concrete url paths:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/shopping-carts/de:1681e6b88ec1/items/1/shopping-carts/de:1681e6b88ec1/content/images/9cacb4d8/content/images/code>/pre>/div>/div>div classparagraph>p>strong>Note:/strong> resource identifiers may be build of multiple other resourceidentifiers (see a href#241>span classmay-keyword>strong>MAY/strong>/span> expose compound keys as resource identifiers/a>)./p>/div>div classparagraph>p>strong>Exception:/strong> In some situations the resource identifier is not passedas a path segment but via the authorization information, e.g. anauthorization token or session cookie.Here, it is reasonable to use strong>code>self/code>/strong> as em>pseudo-identifier/em> path segment.For instance, you may define code>/employees/self/code> or code>/employees/self/personal-details/code>as resource paths — and may additionally define endpoints that supportidentifier passing in the resource path, like define code>/employees/a href#id>code>id/code>/a>/code>or code>/employees/a href#id>code>id/code>/a>/personal-details/code>./p>/div>/div>div classsect2>h3 id241>a classlink href#241>10.7. span classmay-keyword>strong>MAY/strong>/span> expose compound keys as resource identifiers/a>/h3>div classparagraph>p>If a resource is best identified by a em>compound key/em> consisting of multipleother resource identifiers, it is allowed to reuse the compound key in itsnatural form containing slashes instead of em>technical/em> resource identifier inthe resource path without violating the above rule a href#143>span classmust-keyword>strong>MUST/strong>/span> identify resources and sub-resources via path segments/a> as follows:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/resources/{compound-key-1}delim-1...delim-n-1{compound-key-n}/code>/pre>/div>/div>div classparagraph>p>Example paths:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/shopping-carts/{country}/{session-id}/shopping-carts/{country}/{session-id}/items/{item-id}/api-specifications/{docker-image-id}/apis/{path}/{file-name}/api-specifications/{repository-name}/{artifact-name}:{tag}/article-size-advices/{sku}/{sales-channel}/code>/pre>/div>/div>div classparagraph>p>strong>Warning:/strong> Exposing a compound key as described above limits ability toevolve the structure of the resource identifier as it is no longer opaque./p>/div>div classparagraph>p>To compensate for this drawback, APIs must apply a compound key abstractionconsistently in all requests and responses parameters and attributes allowingconsumers to treat these as em>technical resource identifier/em> replacement. Theuse of independent compound key components must be limited to search andcreation requests, as follows:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp># compound key components passed as independent search query parametersGET /article-size-advices?skussku-1,sku-2&sales_channel_idsid-1> { items: { id: id-1, ... },{ id: id-2, ... } }# opaque technical resource identifier passed as path parameterGET /article-size-advices/id-1> { id: id-1, sku: sku-1, sales_channel_id: sid-1, size: ... }# compound key components passed as mandatory request fieldsPOST /article-size-advices { sku: sku-1, sales_channel_id: sid-1, size: ... }> { id: id-1, sku: sku-1, sales_channel_id: sid-1, size: ... }/code>/pre>/div>/div>div classparagraph>p>Where code>id-1/code> is representing the opaque provision of the compound keycode>sku-1/sid-1/code> as technical resource identifier./p>/div>div classparagraph>p>strong>Remark:/strong> A compound key component may itself be used as another resourceidentifier providing another resource endpoint, e.g code>/article-size-advices/{sku}/code>./p>/div>/div>div classsect2>h3 id145>a classlink href#145>10.8. span classmay-keyword>strong>MAY/strong>/span> consider using (non-)nested URLs/a>/h3>div classparagraph>p>If a sub-resource is only accessible via its parent resource and may not existwithout parent resource, consider using a nested URL structure, for instance:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/shoping-carts/de/1681e6b88ec1/cart-items/1/code>/pre>/div>/div>div classparagraph>p>However, if the resource can be accessed directly via its unique id, then theAPI should expose it as a top-level resource. For example, customer has acollection for sales orders; however, sales orders have globally unique id andsome services may choose to access the orders directly, for instance:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/customers/1637asikzec1/sales-orders/5273gh3k525a/code>/pre>/div>/div>/div>div classsect2>h3 id144>a classlink href#144>10.9. span classshould-keyword>strong>SHOULD/strong>/span> only use UUIDs if necessary/a>/h3>div classparagraph>p>Generating IDs can be a scaling problem in high frequency and near real timeuse cases. UUIDs solve this problem, as they can be generated withoutcollisions in a distributed, non-coordinated way and without additional serverround trips./p>/div>div classparagraph>p>However, they also come with some disadvantages:/p>/div>div classulist>ul>li>p>cannot be memorized and easily communicated by humans/p>/li>li>p>less convenient for consumer facing usage/p>/li>li>p>quite long: readable representation requires 36 characters and comes withhigher memory and bandwidth consumption/p>/li>li>p>not ordered along their creation history and no indication of used id volume/p>/li>li>p>may be in conflict with additional backward compatibility support of legacyids/p>/li>/ul>/div>div classparagraph>p>UUIDs should be avoided when not needed for large scale id generation. Instead,for instance, server side support with id generation can be preferred (a href#post>code>POST/code>/a>on id resource, followed by idempotent a href#put>code>PUT/code>/a> on entity resource). Usage ofUUIDs is especially discouraged as primary keys of master and configurationdata, like brand-ids or attribute-ids which have low id volume but widespreadsteering functionality./p>/div>div classparagraph>p>Please be aware that sequential, strictly monotonically increasing numericidentifiers may reveal critical, confidential business information, like ordervolume, to non-privileged clients./p>/div>div classparagraph>p>In any case, we should always use string rather than number type foridentifiers. This gives us more flexibility to evolve the identifier namingscheme. Accordingly, if used as identifiers, UUIDs should not be qualifiedusing a format property./p>/div>div classparagraph>p>Hint: Usually, random UUID is used - see UUID version 4 in a hrefhttps://tools.ietf.org/html/rfc4122>RFC 4122/a>.Though UUID version 1 also contains leading timestamps it is not reflected byits lexicographic sorting. This deficit is addressed bya hrefhttps://github.com/alizain/ulid>ULID/a> (Universally Unique LexicographicallySortable Identifier). You may favour ULID instead of UUID, for instance, forpagination use cases ordered along creation time./p>/div>/div>div classsect2>h3 id146>a classlink href#146>10.10. span classshould-keyword>strong>SHOULD/strong>/span> limit number of resource types/a>/h3>div classparagraph>p>To keep maintenance and service evolution manageable, we should followfunctional segmentation and separation of concern design principles and donot mix different business functionalities in same API definition. In practicethis means that the number of resource types exposed via an API should belimited. In this context a resource type is defined as a set of highly relatedresources such as a collection, its members and any direct sub-resources./p>/div>div classparagraph>p>For example, the resources below would be counted as three resource types, onefor customers, one for the addresses, and one for the customers relatedaddresses:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>/customers/customers/{id}/customers/{id}/preferences/customers/{id}/addresses/customers/{id}/addresses/{addr}/addresses/addresses/{addr}/code>/pre>/div>/div>div classparagraph>p>Note that:/p>/div>div classulist>ul>li>p>We consider code>/customers/a href#id>code>id/code>/a>/preferences/code> part of the code>/customers/code> resourcetype because it has a one-to-one relation to the customer without anadditional identifier./p>/li>li>p>We consider code>/customers/code> and code>/customers/a href#id>code>id/code>/a>/addresses/code> as separate resourcetypes because code>/customers/a href#id>code>id/code>/a>/addresses/{addr}/code> also exists with anadditional identifier for the address./p>/li>li>p>We consider code>/addresses/code> and code>/customers/a href#id>code>id/code>/a>/addresses/code> as separate resourcetypes because there’s no reliable way to be sure they are the same./p>/li>/ul>/div>div classparagraph>p>Given this definition, our experience is that well defined APIs involve no morethan 4 to 8 resource types. There may be exceptions with more complex businessdomains that require more resources, but you should first check if you cansplit them into separate subdomains with distinct APIs./p>/div>div classparagraph>p>Nevertheless one API should hold all necessary resources to model completebusiness processes helping clients to understand these flows./p>/div>/div>div classsect2>h3 id147>a classlink href#147>10.11. span classshould-keyword>strong>SHOULD/strong>/span> limit number of sub-resource levels/a>/h3>div classparagraph>p>There are main resources (with root url paths) and sub-resources (or em>nested/em>resources with non-root urls paths). Use sub-resources if their life cycle is(loosely) coupled to the main resource, i.e. the main resource works ascollection resource of the subresource entities. You should use ⇐ 3sub-resource (nesting) levels — more levels increase API complexity and urlpath length. (Remember, some popular web browsers do not support URLs of morethan 2000 characters.)/p>/div>/div>/div>/div>div classsect1>h2 idhttp-requests>a classlink href#http-requests>11. HTTP requests/a>/h2>div classsectionbody>div classsect2>h3 id148>a classlink href#148>11.1. span classmust-keyword>strong>MUST/strong>/span> use HTTP methods correctly/a>/h3>div classparagraph>p>Be compliant with the standardized HTTP method semantics summarized as follows:/p>/div>div classsect3>h4 idget>a classlink href#get>11.1.1. GET/a>/h4>div classparagraph>p>a href#get>code>GET/code>/a> requests are used to strong>read/strong> either a single or a collection resource./p>/div>div classulist>ul>li>p>a href#get>code>GET/code>/a> requests for individual resources will usually generate a a href#status-code-404 classstatus-code>404/a> if theresource does not exist or is not visible/p>/li>li>p>a href#get>code>GET/code>/a> requests for collection resources may return either a href#status-code-200 classstatus-code>200/a> (if thecollection is empty) or a href#status-code-404 classstatus-code>404/a> (if the collection is missing)/p>/li>li>p>a href#get>code>GET/code>/a> requests must NOT have a request body payload (see a href#get-with-body>code>GET with body/code>/a>)/p>/li>/ul>/div>/div>div classsect3>h4 idget-with-body>a classlink href#get-with-body>11.1.2. GET with body payload/a>/h4>div classparagraph>p>APIs sometimes face the problem, that they have to provide extensive structuredrequest information with a href#get>code>GET/code>/a>, that may conflict with the size limits ofclients, load-balancers, and servers. As we require APIs to be standard conform(request body payload in a href#get>code>GET/code>/a> must be ignored on server side), API designers have to check thefollowing two options:/p>/div>div classolist arabic>ol classarabic>li>p>a href#get>code>GET/code>/a> with URL encoded query parameters: when it is possible to encode therequest information in query parameters, respecting the usual size limits ofclients, gateways, and servers, this should be the first choice. The requestinformation can either be provided via multiple query parameters or by asingle structured URL encoded string./p>/li>li>p>a href#post>code>POST/code>/a> with body payload content: when a a href#get>code>GET/code>/a> with URL encoded query parametersis not possible, a a href#post>code>POST/code>/a> request with body payload must be used, and explicitlydocumented with a hint like in the following example:/p>/li>/ol>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>paths: /products: post: description: > GET with body payload - no resources created: Returns all products matching the query passed as request input payload. requestBody: required: true content: .../code>/pre>/div>/div>/div>div classsect3>h4 idput>a classlink href#put>11.1.3. PUT/a>/h4>div classparagraph>p>a href#put>code>PUT/code>/a> requests are used to strong>update/strong> (in rare cases to create) strong>entire/strong>resources – single or collection resources. The semantic is best describedas em>please put the enclosed representation at the resource mentioned bythe URL, replacing any existing resource./em>./p>/div>div classulist>ul>li>p>a href#put>code>PUT/code>/a> requests are usually applied to single resources, and not to collectionresources, as this would imply replacing the entire collection/p>/li>li>p>a href#put>code>PUT/code>/a> requests are usually robust against non-existence of resources byimplicitly creating before updating/p>/li>li>p>on successful a href#put>code>PUT/code>/a> requests, the server will strong>replace the entire resource/strong>addressed by the URL with the representation passed in the payload (subsequentreads will deliver the same payload)/p>/li>li>p>successful a href#put>code>PUT/code>/a> requests will usually generate a href#status-code-200 classstatus-code>200/a> or a href#status-code-204 classstatus-code>204/a> (if theresource was updated – with or without actual content returned), and a href#status-code-201 classstatus-code>201/a> (ifthe resource was created)/p>/li>/ul>/div>div classparagraph>p>strong>Important:/strong> It is best practice to prefer a href#post>code>POST/code>/a> over a href#put>code>PUT/code>/a> for creation of(at least top-level) resources. This leaves the resource ID under control ofthe service and allows to concentrate on the update semantic using a href#put>code>PUT/code>/a> asfollows./p>/div>div classparagraph>p>strong>Note:/strong> In the rare cases where a href#put>code>PUT/code>/a> is although used for resource creation,the resource IDs are maintained by the client and passed as a URL path segment.Putting the same resource twice is required to be a href#idempotent>idempotent/a> and to resultin the same single resource instance (see a href#149>span classmust-keyword>strong>MUST/strong>/span> fulfill common method properties/a>)./p>/div>/div>div classsect3>h4 idpost>a classlink href#post>11.1.4. POST/a>/h4>div classparagraph>p>a href#post>code>POST/code>/a> requests are idiomatically used to strong>create/strong> single resources on acollection resource endpoint, but other semantics on single resources endpointare equally possible. The semantic for collection endpoints is best describedas em>please add the enclosed representation to the collection resourceidentified by the URL/em>./p>/div>div classulist>ul>li>p>on a successful a href#post>code>POST/code>/a> request, the server will create one or multiple newresources and provide their URI/URLs in the response/p>/li>li>p>successful a href#post>code>POST/code>/a> requests will usually generate a href#status-code-200 classstatus-code>200/a> (if resources havebeen updated), a href#status-code-201 classstatus-code>201/a> (if resources have been created), a href#status-code-202 classstatus-code>202/a> (if the requestwas accepted but has not been finished yet), and exceptionally a href#status-code-204 classstatus-code>204/a> witha hrefhttps://tools.ietf.org/html/rfc7231#section-7.1.2>code>Location/code>/a> header (if the actual resource is not returned)./p>/li>/ul>/div>div classparagraph>p>The semantic for single resource endpoints is best described as em>pleaseexecute the given well specified request on the resource identified by theURL/em>./p>/div>div classparagraph>p>strong>Generally:/strong> a href#post>code>POST/code>/a> should be used for scenarios that cannot be covered by theother methods sufficiently. In such cases, make sure to document the fact thata href#post>code>POST/code>/a> is used as a workaround (see a href#get-with-body>code>GET with body/code>/a>)./p>/div>div classparagraph>p>strong>Note:/strong> Resource IDs with respect to a href#post>code>POST/code>/a> requests are created and maintainedby server and returned with response payload./p>/div>div classparagraph>p>strong>Hint:/strong> Posting the same resource twice is strong>not/strong> required to be a href#idempotent>idempotent/a>(check a href#149>span classmust-keyword>strong>MUST/strong>/span> fulfill common method properties/a>) and may result in multiple resources/p>/div>/div>div classsect3>h4 iddelete>a classlink href#delete>11.1.5. DELETE/a>/h4>div classparagraph>p>a href#delete>code>DELETE/code>/a> requests are used to strong>delete/strong> resources. The semantic is bestdescribed as em>please delete the resource identified by the URL/em>./p>/div>div classulist>ul>li>p>a href#delete>code>DELETE/code>/a> requests are usually applied to single resources, not oncollection resources, as this would imply deleting the entire collection./p>/li>li>p>a href#delete>code>DELETE/code>/a> request can be applied to multiple resources at once using queryparameters on the collection resource (see a href#delete-with-query-params>DELETE with query parameters/a>)./p>/li>li>p>successful a href#delete>code>DELETE/code>/a> requests will usually generate a href#status-code-200 classstatus-code>200/a> (if the deletedresource is returned), a href#status-code-202 classstatus-code>202/a> (if a asynchronous or long running task wassuccessfully started) or a href#status-code-204 classstatus-code>204/a> (if no content is returned)./p>/li>li>p>failed a href#delete>code>DELETE/code>/a> requests will usually generate a href#status-code-404 classstatus-code>404/a> (if the resource cannotbe found) or a href#status-code-410 classstatus-code>410/a> (if the resource was already deleted before)./p>/li>/ul>/div>div classparagraph>p>strong>Important:/strong> After deleting a resource with a href#delete>code>DELETE/code>/a>, a a href#get>code>GET/code>/a> request on theresource is expected to either return a href#status-code-404 classstatus-code>404/a> (not found) or a href#status-code-410 classstatus-code>410/a> (gone)depending on how the resource is represented after deletion. Under nocircumstances the resource must be accessible after this operation on itsendpoint./p>/div>/div>div classsect3>h4 iddelete-with-query-params>a classlink href#delete-with-query-params>11.1.6. DELETE with query parameters/a>/h4>div classparagraph>p>a href#delete>code>DELETE/code>/a> request can have query parameters. Query parameters should be used asfilter parameters on a resource and not for passing context information tocontrol the operation behavior./p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>DELETE /resources?param1value1¶m2value2...¶mNvalueN/code>/pre>/div>/div>div classparagraph>p>strong>Note:/strong> When providing a href#delete>code>DELETE/code>/a> with query parameters, API designers mustcarefully document the behavior in case of (partial) failures to manage clientexpectations properly./p>/div>div classparagraph>p>The response status code of a href#delete>code>DELETE/code>/a> with query parameters requests should besimilar to usual a href#delete>code>DELETE/code>/a> requests./p>/div>/div>div classsect3>h4 iddelete-with-body>a classlink href#delete-with-body>11.1.7. DELETE with body payload/a>/h4>div classparagraph>p>In rare cases a href#delete>code>DELETE/code>/a> may require additional information, that cannot beclassified as filter parameters and thus should be transported via request body payload, toperform the operation. Since a hrefhttps://tools.ietf.org/html/rfc7231#section-4.3.5>RFC-7231/a> states, thata href#delete>code>DELETE/code>/a> has an undefined semantic for payloads, we recommend to utilize a href#post>code>POST/code>/a>.In this case the POST endpoint must be documented with the hint a href#delete-with-body>code>DELETE with body/code>/a>analog to how it is defined for a href#get-with-body>code>GET with body/code>/a>. The response status code ofa href#delete-with-body>code>DELETE with body/code>/a> requests should be similar to usual a href#delete>code>DELETE/code>/a> requests./p>/div>/div>div classsect3>h4 idPATCH>a classlink href#PATCH>11.1.8. PATCH/a>/h4>div classparagraph>p>When using the HTTP verb PATCH as defined in RFC5789 we add the following guidance.As PATCH in contrast to PUT is by itself neither safe nor idempotent as the RFC recognizeswe add the following restrictions to regain the idempotency attribute./p>/div>div classparagraph>p>The PATCH operation SHOULD be idempotent. The preferred pattern to do that SHOULD beRFC 7396 which defines body and content type of a JSON structure./p>/div>div classparagraph>p>strong>Example from RFC7396:/strong>/p>/div>div classlistingblock>div classcontent>pre>For example, given the following original JSON document:{ a: b, c: { d: e, f: g }}Changing the value of a and removing f can be achieved bysending:PATCH /target HTTP/1.1Host: example.orgContent-Type: application/merge-patch+json{ a:z, c: { f: null }}/pre>/div>/div>div classparagraph>p>However, this format is unable to do certain non-idempotent operations.Especially modification of arrays are not entirely possible./p>/div>div classparagraph>p>If that for some reason is really necessary, the format of RFC 6902 which definesmore complex operations is preferred. The operation set of RFC 6902 is also not completeand does not offer the ability to do patch operations on child elements in one operation with certainty./p>/div>div classparagraph>p>For all PATCH operations independent of which body schema is used the following rules apply./p>/div>div classparagraph>p>In case the underlying data model does not permit removal of an attribute a PATCH operationwhich requests this MUST fail. The same holds true if any other data model restrictions are violated.A PATCH request MAY update more than one, up to all attributes of a resource.The API MUST fail all or none of the attribute patches as HTTP PATCH is an atomic operation as defined in RFC5789.Thus, if at least one attribute patch operation fails the whole operation fails.Whatever body is used, the respective content type MUST be announced in the Accept-Patch headerof the OPTIONS call according to RFC5789 when the OPTIONS method is offered.Furthermore, the Content-Type of the PATCH request MUST define the schema used in the body./p>/div>div classparagraph>p>strong>OPTIONS Request example from RFC 5789 with adapted with our chosen PATCH formats:/strong>/p>/div>div classlistingblock>div classcontent>pre>3.2. Example OPTIONS Request and Response request OPTIONS /example/buddies.xml HTTP/1.1 Host: www.example.com response HTTP/1.1 200 OK Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH Accept-Patch: application/merge-patch+json, application/json-patch+json The examples show a server that supports PATCH generally using two hypothetical patch document formats./pre>/div>/div>div classparagraph>p>The resulting error body SHALL indicate which attribute(s) led to the failure of the operation if it wasdue to a subset of attributes causing the failure (i.e. trying a patch on the ID of a resource)./p>/div>/div>/div>div classsect2>h3 id149>a classlink href#149>11.2. span classmust-keyword>strong>MUST/strong>/span> fulfill common method properties/a>/h3>div classparagraph>p>Request methods in RESTful services can be…/p>/div>div classulist>ul>li>p>a idsafe>/a>a hrefhttps://tools.ietf.org/html/rfc7231#section-4.2.1>safe/a> - the operation semantic is defined to be read-only,meaning it must not have em>intended side effects/em>, i.e. changes, to the serverstate./p>/li>li>p>a ididempotent>/a>a hrefhttps://tools.ietf.org/html/rfc7231#section-4.2.2>idempotent/a> - the operation has the sameem>intended effect/em> on the server state, independently whether it is executedonce or multiple times. strong>Note:/strong> this does not require that the operation isreturning the same response or status code./p>/li>li>p>a idcacheable>/a>a hrefhttps://tools.ietf.org/html/rfc7231#section-4.2.3>cacheable/a> - to indicate that responses areallowed to be stored for future reuse. In general, requests to safe methodsare cachable, if it does not require a current or authoritative responsefrom the server./p>/li>/ul>/div>div classparagraph>p>strong>Note:/strong> The above definitions, of em>intended (side) effect/em> allows the serverto provide additional state changing behavior as logging, accounting, pre-fetching, etc. However, these actual effects and state changes, must not beintended by the operation so that it can be held accountable./p>/div>div classparagraph>p>Method implementations must fulfill the following basic properties accordingto a hrefhttps://tools.ietf.org/html/rfc7231>RFC 7231/a>:/p>/div>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 15%;>col stylewidth: 15%;>col stylewidth: 35%;>col stylewidth: 35%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>Method/th>th classtableblock halign-left valign-top>Safe/th>th classtableblock halign-left valign-top>Idempotent/th>th classtableblock halign-left valign-top>Cacheable/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>a href#get>code>GET/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmay-keyword>✔/span> Yes/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmay-keyword>✔/span> Yes/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmay-keyword>✔/span> Yes/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a href#put>code>PUT/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmay-keyword>✔/span> Yes/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a href#delete>code>DELETE/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmay-keyword>✔/span> Yes/p>/td>td classtableblock halign-left valign-top>p classtableblock>span classmust-keyword>✗/span> No/p>/td>/tr>/tbody>/table>/div>div classsect2>h3 id236>a classlink href#236>11.3. span classshould-keyword>strong>SHOULD/strong>/span> design simple query languages using query parameters/a>/h3>div classparagraph>p>We prefer the use of query parameters to describe resource-specificquery languages for the majority of APIs because it’s native to HTTP,easy to extend and has excellent implementation support in HTTP clientsand web frameworks./p>/div>div classparagraph>p>Query parameters should have the following aspects specified:/p>/div>div classulist>ul>li>p>Reference to corresponding property, if any/p>/li>li>p>Value range, e.g. inclusive vs. exclusive/p>/li>li>p>Comparison semantics (equals, less than, greater than, etc)/p>/li>li>p>Implications when combined with other queries, e.g. em>and/em> vs. em>or/em>/p>/li>/ul>/div>div classparagraph>p>How query parameters are named and used is up to individual API designers.The following examples should serve as ideas:/p>/div>div classulist>ul>li>p>code>nameBosch/code>, to query for elements based on property equality/p>/li>li>p>code>age5/code>, to query for elements based on logical properties/p>div classulist>ul>li>p>Assuming that elements don’t actually have an code>age/code> but rather a code>birthday/code>/p>/li>/ul>/div>/li>li>p>code>max_length5/code>, based on upper and lower bounds (code>min/code> and code>max/code>)/p>/li>li>p>code>shorter_than5/code>, using terminology specific e.g. to em>length/em>/p>/li>li>p>code>created_before2019-07-17/code> or code>not_modified_since2019-07-17/code>/p>div classulist>ul>li>p>Using terminology specific e.g. to time: em>before/em>, em>after/em>, em>since/em> and em>until/em>/p>/li>/ul>/div>/li>/ul>/div>div classparagraph>p>We don’t advocate for or against certain names because in the endAPIs should be free to choose the terminology that fits their domain the best./p>/div>/div>div classsect2>h3 id237>a classlink href#237>11.4. span classshould-keyword>strong>SHOULD/strong>/span> design complex query languages using JSON/a>/h3>div classparagraph>p>Minimalistic query languages based on a href#236>query parameters/a> are suitablefor simple use cases with a small set of available filters that are combinedin one way and one way only (e.g. em>and/em> semantics). Simple query languages aregenerally preferred over complex ones./p>/div>div classparagraph>p>Some APIs will have a need for sophisticated and more complex query languages.Dominant examples are APIs around search (incl. faceting) and product catalogs./p>/div>div classparagraph>p>Aspects that set those APIs apart from the rest include but are not limited to:/p>/div>div classulist>ul>li>p>Unusual high number of available filters/p>/li>li>p>Dynamic filters, due to a dynamic and extensible resource model/p>/li>li>p>Free choice of operators, e.g. code>and/code>, code>or/code> and code>not/code>/p>/li>/ul>/div>div classparagraph>p>APIs that qualify for a specific, complex query language are encouraged touse nested JSON data structures and define them using Open API directly. Theprovides the following benefits:/p>/div>div classulist>ul>li>p>Data structures are easy to use for clients/p>div classulist>ul>li>p>No special library support necessary/p>/li>li>p>No need for string concatenation or manual escaping/p>/li>/ul>/div>/li>li>p>Data structures are easy to use for servers/p>div classulist>ul>li>p>No special tokenizers needed/p>/li>li>p>Semantics are attached to data structures rather than text tokens/p>/li>/ul>/div>/li>li>p>Consistent with other HTTP methods/p>/li>li>p>API is defined in Open API completely/p>div classulist>ul>li>p>No external documents or grammars needed/p>/li>li>p>Existing means are familiar to everyone/p>/li>/ul>/div>/li>/ul>/div>div classparagraph>p>a href#json-guidelines>JSON-specific rules/a> and most certainly needs to make useof the a href#get-with-body>code>GET/code>-with-body/a> pattern./p>/div>div classsect3>h4 id_example>a classlink href#_example>11.4.1. Example/a>/h4>div classparagraph>p>The following JSON document should serve as an idea how a structured querymight look like./p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-json hljs data-langjson>{ and: { name: { match: Alice }, age: { or: { range: { >: 25, <: 50 }, : 65 } } }}/code>/pre>/div>/div>div classparagraph>p>Feel free to also get some inspiration from:/p>/div>div classulist>ul>li>p>a hrefhttps://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html>Elastic Search: Query DSL/a>/p>/li>li>p>a hrefhttps://graphql.org/learn/queries/>GraphQL: Queries/a>/p>/li>/ul>/div>/div>/div>/div>/div>div classsect1>h2 idhttp-status-codes-and-errors>a classlink href#http-status-codes-and-errors>12. HTTP status codes and errors/a>/h2>div classsectionbody>div classsect2>h3 id151>a classlink href#151>12.1. span classmust-keyword>strong>MUST/strong>/span> specify success and error responses/a>/h3>div classparagraph>p>APIs should define the functional, business view and abstract fromimplementation aspects. Success and error responses are a vital part todefine how an API is used correctly./p>/div>div classparagraph>p>Therefore, you must define strong>all/strong> success and service specific errorresponses in your API specification. Both are part of the interface definitionand provide important information for service clients to handle standard aswell as exceptional situations./p>/div>div classparagraph>p>strong>Hint:/strong> In most cases it is not useful to document all technical errors,especially if they are not under control of the service provider. Thus unlessa response code conveys application-specific functional semantics or is usedin a none standard way that requires additional explanation, multiple errorresponse specifications can be combined using the following pattern/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>responses: ... default: description: error occurred - see status code and problem object for more information. content: application/problem+json: schema: $ref: #/definitions/Problem/code>/pre>/div>/div>/div>div classsect2>h3 id150>a classlink href#150>12.2. span classmust-keyword>strong>MUST/strong>/span> use standard HTTP status codes/a>/h3>div classparagraph>p>You must only use standardized HTTP status codes consistently with theirintended semantics. You must not invent new HTTP status codes./p>/div>div classparagraph>p>Below we list the most commonly used and best understood HTTP status codes,consistent with their semantic in the RFCs. APIs should only use these toprevent misconceptions that arise from less commonly used HTTP status codes./p>/div>div classparagraph>p>strong>Important:/strong> As long as your HTTP status code usage is well covered by thesemantic defined here, you should not describe it to avoid an overload withcommon sense information and the risk of inconsistent definitions. Only if theHTTP status code is not in the list below or its usage requires additionalinformation aside the well defined semantic, the API specification must providea clear description of the HTTP status code in the response./p>/div>div classsect3>h4 idsuccess-codes>a classlink href#success-codes>12.2.1. Success codes/a>/h4>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 10%;>col stylewidth: 70%;>col stylewidth: 20%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>Code/th>th classtableblock halign-left valign-top>Meaning/th>th classtableblock halign-left valign-top>Methods/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-200>/a>a href#status-code-200 classstatus-code>200/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>OK - this is the standard success response/p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-201>/a>a href#status-code-201 classstatus-code>201/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Created - Returned on successful entity creation. You arefree to return either an empty response or the created resource in conjunctionwith the Location header.em>Always/em> set the Location header./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>, a href#put>code>PUT/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-202>/a>a href#status-code-202 classstatus-code>202/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Accepted - The request was successful and will be processed asynchronously./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-204>/a>a href#status-code-204 classstatus-code>204/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>No content - There is no response body./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>/tbody>/table>/div>div classsect3>h4 idredirection-codes>a classlink href#redirection-codes>12.2.2. Redirection codes/a>/h4>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 10%;>col stylewidth: 70%;>col stylewidth: 20%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>Code/th>th classtableblock halign-left valign-top>Meaning/th>th classtableblock halign-left valign-top>Methods/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-301>/a>a href#status-code-301 classstatus-code>301/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Moved Permanently - This and all future requests should be directed to thegiven URI./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-302>/a>{302}/p>/td>td classtableblock halign-left valign-top>p classtableblock>Found - The resource requested has been temporarily moved to the URL given by the URI./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-303>/a>a href#status-code-303 classstatus-code>303/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>See Other - The response to the request can be found under another URI using aa href#get>code>GET/code>/a> method./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>, a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-304>/a>a href#status-code-304 classstatus-code>304/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Not Modified - indicates that a conditional GET or HEAD request would haveresulted in 200 response if it were not for the fact that the condition evaluatedto false, i.e. resource has not been modified since the date or version passedvia request headers If-Modified-Since or If-None-Match./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#get>code>GET/code>/a>, a href#head>code>HEAD/code>/a>/p>/td>/tr>/tbody>/table>/div>div classsect3>h4 idclient-side-error-codes>a classlink href#client-side-error-codes>12.2.3. Client side error codes/a>/h4>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 10%;>col stylewidth: 70%;>col stylewidth: 20%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>Code/th>th classtableblock halign-left valign-top>Meaning/th>th classtableblock halign-left valign-top>Methods/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-400>/a>a href#status-code-400 classstatus-code>400/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Bad request - generic / unknown error. Should also be delivered in case ofinput payload fails business logic validation./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-401>/a>a href#status-code-401 classstatus-code>401/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Unauthorized - the users must log in (this often means Unauthenticated)./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-403>/a>a href#status-code-403 classstatus-code>403/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Forbidden - the user is not authorized to use this resource./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-404>/a>a href#status-code-404 classstatus-code>404/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Not found - the resource is not found./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-405>/a>a href#status-code-405 classstatus-code>405/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Method Not Allowed - the method is not supported, see a href#options>code>OPTIONS/code>/a>./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-406>/a>a href#status-code-406 classstatus-code>406/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Not Acceptable - resource can only generate content not acceptable accordingto the Accept headers sent in the request./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-408>/a>a href#status-code-408 classstatus-code>408/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Request timeout - the server times out waiting for the resource./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-409>/a>a href#status-code-409 classstatus-code>409/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Conflict - request cannot be completed due to conflict, e.g. when two clientstry to create the same resource or if there are concurrent, conflicting updates./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>, a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-410>/a>a href#status-code-410 classstatus-code>410/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Gone - resource does not exist any longer, e.g. when accessing aresource that has intentionally been deleted./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-412>/a>a href#status-code-412 classstatus-code>412/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Precondition Failed - returned for conditional requests, e.g. a hrefhttps://tools.ietf.org/html/rfc7232#section-3.1>code>If-Match/code>/a> if thecondition failed. Used for optimistic locking./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#get>code>GET/code>/a>, a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-415>/a>a href#status-code-415 classstatus-code>415/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Unsupported Media Type - e.g. clients sends request body without content type./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>, a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-422>/a>{422}/p>/td>td classtableblock halign-left valign-top>p classtableblock>Unprocessable Entity - e.g. information model or business rules prohibit fulfilling the request/p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#post>code>POST/code>/a>, a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-423>/a>a href#status-code-423 classstatus-code>423/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Locked - Pessimistic locking, e.g. processing states./p>/td>td classtableblock halign-left valign-top>p classtableblock>a href#put>code>PUT/code>/a>, a href#patch>code>PATCH/code>/a>, a href#delete>code>DELETE/code>/a>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-429>/a>a href#status-code-429 classstatus-code>429/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Too many requests - the client does not consider rate limiting and sent toomany requests./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>/tbody>/table>/div>div classsect3>h4 idserver-side-error-codes>a classlink href#server-side-error-codes>12.2.4. Server side error codes:/a>/h4>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 10%;>col stylewidth: 70%;>col stylewidth: 20%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>Code/th>th classtableblock halign-left valign-top>Meaning/th>th classtableblock halign-left valign-top>Methods/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-500>/a>a href#status-code-500 classstatus-code>500/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Internal Server Error - a generic error indication for an unexpected serverexecution problem (here, client retry may be sensible)/p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-501>/a>a href#status-code-501 classstatus-code>501/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Not Implemented - server cannot fulfill the request (usually implies futureavailability, e.g. new feature)./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-502>/a>{502}/p>/td>td classtableblock halign-left valign-top>p classtableblock>Bad Gateway - server cannot fulfill the request (usually implies futureavailability, e.g. new feature)./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>tr>td classtableblock halign-left valign-top>p classtableblock>a idstatus-code-503>/a>a href#status-code-503 classstatus-code>503/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>Service Unavailable - service is (temporarily) not available (e.g. if arequired component or downstream service is not available) — client retry maybe sensible. If possible, the service should indicate how long the clientshould wait by setting the a hrefhttps://tools.ietf.org/html/rfc7231#section-7.1.3>code>Retry-After/code>/a> header./p>/td>td classtableblock halign-left valign-top>p classtableblock>code><all>/code>/p>/td>/tr>/tbody>/table>/div>/div>div classsect2>h3 id220>a classlink href#220>12.3. span classmust-keyword>strong>MUST/strong>/span> use most specific HTTP status codes/a>/h3>div classparagraph>p>You must use the most specific HTTP status code when returning informationabout your request processing status or error situations./p>/div>/div>div classsect2>h3 id176>a classlink href#176>12.4. span classmust-keyword>strong>MUST/strong>/span> support problem JSON/a>/h3>div classparagraph>p>a hrefhttps://tools.ietf.org/html/rfc7807>RFC 7807/a> defines a Problem JSON object using the media typecode>application/problem+json/code> to provide an extensible human and machine readablefailure information beyond the HTTP response status code to transports thefailure kind (code>type/code> / code>title/code>) and the failure cause and location (code>instance/code> /code>detail/code>). To make best use of this additional failure information, everyendpoints must be capable of returning a Problem JSON on client usage errors(a href#client-side-error-codes classstatus-code>4xx/a> status codes) as well as server side processing errors (a href#server-side-error-codes classstatus-code>5xx/a> statuscodes)./p>/div>div classparagraph>p>strong>Note:/strong> Clients must be robust and strong>not rely/strong> on a Problem JSON objectbeing returned, since (a) failure responses may be created by infrastructurecomponents not aware of this guideline or (b) service may be unable to complywith this guidelines in certain error situations./p>/div>div classparagraph>p>The Open API schema definition of the Problem JSON object can be found here:/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-yaml hljs data-langyaml>Problem: type: object properties: type: type: string format: uri-reference description: > A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type. default: about:blank example: /problem/connection-error title: type: string description: > A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized. example: Service Unavailable status: type: integer format: int32 description: > The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 100 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: > A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized. example: Connection to database timed out instance: type: string format: uri-reference description: > A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code. example: /problem/connection-error#token-info-read-timed-out/code>/pre>/div>/div>div classparagraph>p>Copy it to your specification reference it as schema type. You may extend the problem type if your API needs to return specific, additional, and more detailed error information./p>/div>/div>div classsect2>h3 id177>a classlink href#177>12.5. span classmust-keyword>strong>MUST/strong>/span> not expose stack traces/a>/h3>div classparagraph>p>Stack traces contain implementation details that are not part of an API,and on which clients should never rely. Moreover, stack traces can leaksensitive information that partners and third parties are not allowed toreceive and may disclose insights about vulnerabilities to attackers./p>/div>/div>/div>/div>div classsect1>h2 idperformance>a classlink href#performance>13. Performance/a>/h2>div classsectionbody>div classsect2>h3 id155>a classlink href#155>13.1. span classshould-keyword>strong>SHOULD/strong>/span> reduce bandwidth needs and improve responsiveness/a>/h3>div classparagraph>p>APIs should support techniques for reducing bandwidth based on client needs.This holds for APIs that (might) have high payloads and/or are used inhigh-traffic scenarios like the public Internet and telecommunication networks./p>/div>div classparagraph>p>Common techniques include:/p>/div>div classulist>ul>li>p>compression of request and response bodies (see a href#156>span classshould-keyword>strong>SHOULD/strong>/span> use code>gzip/code> compression/a>)/p>/li>li>p>pagination for incremental access of larger collections of data items (see a href#159>span classmust-keyword>strong>MUST/strong>/span> support pagination/a>)/p>/li>li>p>caching of master data items, i.e. resources that change rarely or notat all after creation./p>/li>/ul>/div>/div>div classsect2>h3 id156>a classlink href#156>13.2. span classshould-keyword>strong>SHOULD/strong>/span> use code>gzip/code> compression/a>/h3>div classparagraph>p>Compress the payload of your API’s responses with gzip, unless there’s a goodreason not to — for example, you are serving so many requests that the time tocompress becomes a bottleneck. This helps to transport data faster over thenetwork (fewer bytes) and makes frontends respond faster./p>/div>div classparagraph>p>Though gzip compression might be the default choice for server payload, theserver should also support payload without compression and its client controlvia a hrefhttps://tools.ietf.org/html/rfc7231#section-5.3.4>code>Accept-Encoding/code>/a> request header — see also a hrefhttps://tools.ietf.org/html/rfc7231#section-5.3.4>RFC7231 Section 5.3.4/a>. The server should indicate used gzip compression via thea hrefhttps://tools.ietf.org/html/rfc7231#section-3.1.2.2>code>Content-Encoding/code>/a> header./p>/div>/div>div classsect2>h3 id158>a classlink href#158>13.3. span classshould-keyword>strong>SHOULD/strong>/span> allow optional embedding of sub-resources/a>/h3>div classparagraph>p>Embedding related resources (also knowm as em>Resource expansion/em>) is agreat way to reduce the number of requests. In cases where clients knowupfront that they need some related resources they can instruct theserver to prefetch that data eagerly. Whether this is optimized on theserver, e.g. a database join, or done in a generic way, e.g. an HTTPproxy that transparently embeds resources, is up to the implementation./p>/div>div classparagraph>p>See a href#137>span classmust-keyword>strong>MUST/strong>/span> stick to conventional query parameters/a> for naming, e.g. embed for steering of embeddedresource expansion. Please use thea hrefhttps://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>BNF/a> grammar, asalready defined above for filtering, when it comes to an embedding querysyntax./p>/div>div classparagraph>p>Embedding a sub-resource can possibly look like this where an orderresource has its order items as sub-resource (/order/{orderId}/items):/p>/div>div classlistingblock>div classcontent>pre classhighlightjs highlight>code classlanguage-http hljs data-langhttp>GET /order/123?embed(items) HTTP/1.1{ id: 123, _embedded: { items: { position: 1, sku: 1234-ABCD-7890, price: { amount: 71.99, currency: EUR } } }}/code>/pre>/div>/div>/div>div classsect2>h3 id159>a classlink href#159>13.4. span classmust-keyword>strong>MUST/strong>/span> support pagination/a>/h3>div classparagraph>p>Access to lists of data items must support pagination to protect the serviceagainst overload as well as for best client side iteration and batch processingexperience. This holds true for all lists that are (potentially) larger thanjust a few hundred entries./p>/div>div classparagraph>p>There are two well known page iteration techniques:/p>/div>div classulist>ul>li>p>a hrefhttps://developer.infoconnect.com/paging-results>Offset/Limit-basedpagination/a>: numeric offset identifies the first page entry/p>/li>li>p>a hrefhttps://dev.twitter.com/overview/api/cursoring>Cursor/Limit-based/a> — akakey-based — pagination: a unique key element identifies the first page entry(see also a hrefhttps://developers.facebook.com/docs/graph-api/using-graph-api/v2.4#paging>Facebook’s guide/a>)/p>/li>/ul>/div>/div>/div>/div>div classsect1>h2 idhypermedia>a classlink href#hypermedia>14. Hypermedia/a>/h2>div classsectionbody>div classsect2>h3 id162>a classlink href#162>14.1. span classmust-keyword>strong>MUST/strong>/span> use REST maturity level 2/a>/h3>div classparagraph>p>We strive for a good implementation ofa hrefhttp://martinfowler.com/articles/richardsonMaturityModel.html#level2>RESTMaturity Level 2/a> as it enables us to build resource-oriented APIs thatmake full use of HTTP verbs and status codes. You can see this expressedby many rules throughout these guidelines, e.g.:/p>/div>div classulist>ul>li>p>a href#138>span classmust-keyword>strong>MUST/strong>/span> avoid actions - think about resources/a>/p>/li>li>p>a href#141>span classmust-keyword>strong>MUST/strong>/span> keep URLs verb-free/a>/p>/li>li>p>a href#148>span classmust-keyword>strong>MUST/strong>/span> use HTTP methods correctly/a>/p>/li>li>p>a href#150>span classmust-keyword>strong>MUST/strong>/span> use standard HTTP status codes/a>/p>/li>/ul>/div>div classparagraph>p>Although this is not HATEOAS, it should not prevent you from designingproper link relationships in your APIs as stated in rules below./p>/div>/div>div classsect2>h3 id163>a classlink href#163>14.2. span classmay-keyword>strong>MAY/strong>/span> use REST maturity level 3 - HATEOAS/a>/h3>div classparagraph>p>We do not generally recommend to implementa hrefhttp://martinfowler.com/articles/richardsonMaturityModel.html#level3>RESTMaturity Level 3/a>. HATEOAS comes with additional API complexity withoutreal value in our SOA context where client and server interact via RESTAPIs and provide complex business functions as part of our e-commerceplatform./p>/div>/div>/div>/div>div classsect1>h2 idproprietary-headers>a classlink href#proprietary-headers>15. Proprietary headers/a>/h2>div classsectionbody>div classparagraph>p>This section shares definitions of proprietary headers that should benamed consistently because they address overarching service-relatedconcerns. Whether services support these concerns or not is optional;therefore, the Open API API specification is the right place to make thisexplicitly visible. Use the parameter definitions of the resource HTTPmethods./p>/div>div classsect2>h3 id183>a classlink href#183>15.1. span classshould-keyword>strong>SHOULD/strong>/span> use only the specified proprietary BSH headers/a>/h3>div classparagraph>p>As a general rule, proprietary HTTP headers should be avoided.From a conceptual point of view, the business semantics and intent of anoperation should always be expressed via the URLs path and query parameters,the method, and the content, but not via proprietary headers.Headers are typically used to implement protocol processing aspects, such as flow control,content negotiation, and authentication, and represent business agnosticrequest modifiers that provide generic context information (a hrefhttps://tools.ietf.org/html/rfc7231#section-5>RFC 7231/a>)./p>/div>div classparagraph>p>However, the exceptional usage of proprietary headers is still helpfulwhen domain-specific generic context information…/p>/div>div classolist arabic>ol classarabic>li>p>needs to be passed end to end along the service call chain (even ifnot all called services use it as input for steering service behavior)and/or…/p>/li>li>p>is provided by specific gateway components/p>/li>/ol>/div>div classparagraph>p>Below, we explicitly define the list of proprietary header exceptions usable forall services for passing through generic context information./p>/div>div classparagraph>p>Per convention, non standardized, proprietary header names are prefixed with code>X-/code>./p>/div>div classparagraph>p>Remember that HTTP header field names are not case-sensitive:/p>/div>table classtableblock frame-all grid-all stretch>colgroup>col stylewidth: 15%;>col stylewidth: 10%;>col stylewidth: 60%;>col stylewidth: 15%;>/colgroup>thead>tr>th classtableblock halign-left valign-top>Header field name/th>th classtableblock halign-left valign-top>Type/th>th classtableblock halign-left valign-top>Description/th>th classtableblock halign-left valign-top>Header field value example/th>/tr>/thead>tbody>tr>td classtableblock halign-left valign-top>p classtableblock>a idx-flow-id>/a>a href#x-flow-id>code>X-Flow-ID/code>/a>/p>/td>td classtableblock halign-left valign-top>p classtableblock>String/p>/td>td classtableblock halign-left valign-top>p classtableblock>For more information see a href#233>span classmust-keyword>strong>MUST/strong>/span> support code>X-Flow-ID/code>/a>./p>/td>td classtableblock halign-left valign-top>p classtableblock>GKY7oDhpSiKY_gAAAABZ_A/p>/td>/tr>/tbody>/table>div classparagraph>p>strong>Hint:/strong> This guideline does not standardize proprietary headers forgateway components (2. use case above)./p>/div>/div>div classsect2>h3 id184>a classlink href#184>15.2. span classmust-keyword>strong>MUST/strong>/span> propagate proprietary headers/a>/h3>div classparagraph>p>All proprietary headers listed above are end-to-end headers and must bepropagated to the services down the call chain. The header names and values must remain unchanged./p>/div>/div>div classsect2>h3 id233>a classlink href#233>15.3. span classmust-keyword>strong>MUST/strong>/span> support code>X-Flow-ID/code>/a>/h3>div classparagraph>p>The em>Flow-ID/em> is a generic parameter to be passed through service APIs andevents and written into log files and traces. A consequent usage of theem>Flow-ID/em> facilitates the tracking of call flows through our system and allowsthe correlation of service activities initiated by a specific call. This isextremely helpful for operational troubleshooting and log analysis./p>/div>div classsect3>h4 id_data_definition>a classlink href#_data_definition>15.3.1. Data Definition/a>/h4>div classparagraph>p>The following formats are allowed:/p>/div>div classulist>ul>li>p>code>UUID/code> (a hrefhttps://tools.ietf.org/html/rfc4122>RFC-4122/a>)/p>/li>li>p>code>base64/code> (a hrefhttps://tools.ietf.org/html/rfc4648>RFC-4648/a>)/p>/li>li>p>code>base64url/code> (a hrefhttps://tools.ietf.org/html/rfc4648#section-5>RFC-4648 Section 5/a>)/p>/li>li>p>Random unique string restricted to the character set code>a-zA-Z0-9/+_-/code> maximal of 128 characters./p>/li>/ul>/div>/div>/div>/div>/div>div classsect1>h2 idsecurity>a classlink href#security>16. Security/a>/h2>div classsectionbody>div classsect2>h3 id104>a classlink href#104>16.1. span classmust-keyword>strong>MUST/strong>/span> document authentication and authorization mechanisms/a>/h3>div classparagraph>p>Every API must document and specify in the API specification what authentication and authorisation mechanisms are in place./p>/div>div classparagraph>p>So it should be clear for every consumer what kind of credentials or tokens must be provided in order to get access to the API./p>/div>/div>/div>/div>div classsect1>h2 idappendix>a classlink href#appendix>Appendix A: Appendix/a>/h2>div classsectionbody>div classparagraph>p>This section collects links to document to which we refer, and base our guidelines on./p>/div>div classsect2>h3 idspecifications-and-standards>a classlink href#specifications-and-standards>A.1. Specifications and standards/a>/h3>div classulist>ul>li>p>strong>a hrefhttps://github.com/OAI/OpenAPI-Specification/>Open API specification/a>/strong>/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc3339>RFC 3339/a>:/strong> Date and Time on the Internet: Timestamps/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc4122>RFC 4122/a>:/strong> A Universally Unique IDentifier (UUID) URN Namespace/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc4627>RFC 4627/a>:/strong> The application/json Media Type for JavaScript Object Notation (JSON)/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc8288>RFC 8288/a>:/strong> Web Linking/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc6585>RFC 6585/a>:/strong> Additional HTTP Status Codes/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc6902>RFC 6902/a>:/strong> JavaScript Object Notation (JSON) Patch/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7159>RFC 7159/a>:/strong> The JavaScript Object Notation (JSON) Data Interchange Format/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7230>RFC 7230/a>:/strong> Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7231>RFC 7231/a>:/strong> Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7232>RFC 7232/a>:/strong> Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7233>RFC 7233/a>:/strong> Hypertext Transfer Protocol (HTTP/1.1): Range Requests/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7234>RFC 7234/a>:/strong> Hypertext Transfer Protocol (HTTP/1.1): Caching/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7240>RFC 7240/a>:/strong> Prefer Header for HTTP/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7396>RFC 7396/a>:/strong> JSON Merge Patch/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc7807>RFC 7807/a>:/strong> Problem Details for HTTP APIs/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/rfc4648>RFC 4648/a>:/strong> The Base16, Base32, and Base64 Data Encodings/p>/li>li>p>strong>a hrefhttps://en.wikipedia.org/wiki/ISO_8601>ISO 8601/a>:/strong> Date and time format/p>/li>li>p>strong>a hrefhttps://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>ISO 3166-1 alpha-2/a>:/strong> Two letter country codes/p>/li>li>p>strong>a hrefhttps://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>ISO 639-1/a>:/strong> Two letter language codes/p>/li>li>p>strong>a hrefhttps://en.wikipedia.org/wiki/ISO_4217>ISO 4217/a>:/strong> Currency codes/p>/li>li>p>strong>a hrefhttps://tools.ietf.org/html/bcp47>BCP 47/a>:/strong> Tags for Identifying Languages/p>/li>/ul>/div>/div>div classsect2>h3 id_attribution>a classlink href#_attribution>A.2. Attribution/a>/h3>div classparagraph>p>This work, BSH API Guidelines, is a derivative of a hrefhttps://github.com/zalando/restful-api-guidelines>Developing Restful APIs: A Comprehensive Set of Guidelines by Zalando/a> by Zalando, used under CC BY (Creative commons Attribution 4.0). BSH API Guidelines is licensed under CC BY (Creative commons Attribution 4.0) by BSH Hausgeräte GmbH./p>/div>!-- Adds rule id as a postfix to all rule titles -->script>var ruleIdRegEx /(\d)+/;var h3headers document.getElementsByTagName(h3);for (var i 0; i h3headers.length; i++) { var header h3headersi; if (header.id && header.id.match(ruleIdRegEx)) { var a header.getElementsByTagName(a)0 a.innerHTML + + header.id + ; }}/script>!-- Add table of contents anchor and remove document title -->script>var toc document.getElementById(toc);var div document.createElement(div);div.id table-of-contents;toc.parentNode.replaceChild(div, toc);div.appendChild(toc);var ul toc.childNodes3;ul.removeChild(ul.childNodes1);/script>!-- Adds sidebar navigation -->script>var header document.getElementById(header);var nav document.createElement(div);nav.id toc;nav.classList.add(toc2);var title document.createElement(div);title.id toctitle;var link document.createElement(a);link.innerText BSH API Guidelines;link.href #;title.append(link);nav.append(title);var ul document.createElement(ul);ul.classList.add(sectlevel1);var link document.createElement(a);link.innerHTML Table of Contents;link.href #table-of-contents;li document.createElement(li);li.append(link);ul.append(li);var link, li;var h2headers document.getElementsByTagName(h2);for (var i 1; i h2headers.length; i++) { var a h2headersi.getElementsByTagName(a)0; if (a ! undefined) { link document.createElement(a); link.innerHTML a.innerHTML; link.href a.hash; li document.createElement(li); li.append(link); ul.append(li); }}document.body.classList.add(toc2);document.body.classList.add(toc-left);nav.append(ul);header.prepend(nav);/script>/div>/div>/div>/div>div idfootnotes>hr>div classfootnote id_footnotedef_1>a href#_footnoteref_1>1/a>. Per definition of R.Fielding REST APIs have to support HATEOAS (maturity level 3). Our guidelines do not strongly advocate for full REST compliance. However, we still use the term RESTful API, due to the absence of an alternative established term and to keep it like the very majority of web service industry that also use the term for their REST approximations — in fact, in today’s industry full HATEOAS compliant APIs are a very rare exception./div>/div>div idfooter>div idfooter-text>Last updated 2024-09-18 14:35:22 UTC/div>/div>script srchttps://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.3/highlight.min.js>/script>script>if (!hljs.initHighlighting.called) { hljs.initHighlighting.called true ;.slice.call(document.querySelectorAll(pre.highlight > codedata-lang)).forEach(function (el) { hljs.highlightBlock(el) })}/script>/body>/html>
View on OTX
|
View on ThreatMiner
Please enable JavaScript to view the
comments powered by Disqus.
Data with thanks to
AlienVault OTX
,
VirusTotal
,
Malwr
and
others
. [
Sitemap
]