URI formats

As per RFC 3986, the syntax of the generic URI is scheme "://" authority "/" path [ "?" query ] [ "#" fragment ] and following are the rules for API designs:

  • Use forward slash (/) separator: This is used to indicate the hierarchical relationship between resources, for example, http://xx.yy.zz/shapes/polygons/quadrilaterals/squares.
  • Don't use a trailing forward slash: A trailing forward slash in the URI doesn't have any meaning and may create confusion, for example, http://xx.yy.zz/shapes/polygons/ and  http://api.examples.org/shapes/polygons (note the trailing / at the end of the URI). REST API should neither expect trailing slash nor include them in the links that they provide to clients as responses.
  • Use hyphens (-): Hyphens improve the readability of URI names, paths, and segments, and help clients to scan and interpret easily, for example, https://xx.yy.zz/seven-wonders/taj-mahal/india/agra (note the hyphen segregates the space between seven wonders and Taj Mahal).
  • Avoid underscores (_): Designers should avoid _ (underscore) representation in the path, as the character underscore may be partially obscured or hidden while rendering on any visual cues due to computer fonts, for example, https://xx.yy.zz/seven_wonders/taj_mahal/india/agra (note that we can't make out the underscore as its made as a hyperlink). It should use hyphens instead https://xx.yy.zz/seven-wonders/taj-mahal/india/agra (with a hyphen, it's visible even if it is a hyperlink).
  • Prefer all lowercase letters in a URI path: API designers should give preference to lowercase letters over any other representations, as RFC 3986 defines URIs as case sensitive except for the scheme and host components. Some examples include, http://xx.yy.zz/shapes/polygons and  HTTP://XX.YY.ZZ/shapes/polygons are the same, while http://xx.yy.zz/shapes/polygons and HTTP://XX.YY.ZZ/SHAPES/Polygons are not the same.
  • Do not include file extensions: As you know, a dot (.) prefixed after the filename denotes its file types. However, a URI shouldn't use dots to represent any file extensions; instead, it should rely on media types communicated through a content-type header (refer to the media types and media type design rules section).
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.222.35.77