Skip to content

Instantly share code, notes, and snippets.

@amulyakashyap09

amulyakashyap09/rest_naming_conventions.html

Created February 22, 2018 14:21
Show Gist options
  • Save amulyakashyap09/a6a57dada4f71511b2544e0b42a48242 to your computer and use it in GitHub Desktop.
Save amulyakashyap09/a6a57dada4f71511b2544e0b42a48242 to your computer and use it in GitHub Desktop.
Download ZIP
Rest Naming Conventions
Raw
rest_naming_conventions.html
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="exporter-version" content="Evernote Mac 6.13.3 (455969)" />
<meta name="altitude" content="331.4588012695312" />
<meta name="author" content="amulyakashyap09@gmail.com" />
<meta name="created" content="2018-02-22 13:17:51 +0000" />
<meta name="latitude" content="30.71890173873824" />
<meta name="longitude" content="76.8103098519497" />
<meta name="source" content="desktop.mac" />
<meta name="updated" content="2018-02-22 14:18:01 +0000" />
<title>REST NAMING CONVENTIONS</title>
</head>
<body>
<div><font style="font-size: 18px;">Use <b>nouns</b> to represent <b>resources</b> (<u>resource can be your any entity that exists within your model architecture</u>)</font></div>
<div>
<br/>
</div>
<div><span style="text-decoration: underline;">Document/record</span> - Use “<b>singular</b>” name to denote <b>document</b> <b>resource</b> archetype.</div>
<div><span style="text-decoration: underline;">Collection/Table</span> - Use “<b>plural</b>” name to denote <b>collection</b> <b>resource</b> archetype.</div>
<div><span style="text-decoration: underline;">Controller</span> - Use “<b>verb</b>” to denote <b>controller</b> archetype.</div>
<div>
<br/>
</div>
<div>
<ul>
<li>A resource can be a <span style="font-weight: bold;">singleton</span> or a <span style="font-weight: bold;">collection</span>.</li>
<ul>
<li>/customers</li>
<li>/customers/{customerId}</li>
</ul>
<li>A resource may contain <span style="font-weight: bold;">sub-collection</span> resources.</li>
<ul>
<li>/customers/{customerId}/accounts</li>
<li>/customers/{customerId}/accounts/{accountId}</li>
</ul>
</ul>
</div>
<div>
<br/>
</div>
<div><font style="font-size: 18px;"><u>Some best practices to implement REST Api with consistent style</u></font></div>
<div>
<br/>
</div>
<div>
<ul>
<li><b>Use forward slash (/) to indicate a hierarchical relationships</b></li>
<ul>
<li>http://api.url.com/collections/resource</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Do not use trailing forward slash (/) in URIs</b></li>
<ul>
<li>http://api.url.com/collections/resource/ (<span style="font-weight: bold;">wrong</span>)</li>
<li>http://api.url.com/collections/resource (<span style="font-weight: bold;">right</span>)</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Use hypens (-) to improve readability of URI's</b></li>
<ul>
<li>http://api.url.com/mongo-collections/doc-resource</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Do not use underscores (_)</b></li>
<ul>
<li>http://api.url.com/mongo_collections/doc_resource</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Use lowercase letters in URI’s</b></li>
<ul>
<li>http://api.url.com/Collections/Resource (<span style="font-weight: bold;">wrong</span>)</li>
<li>http://api.url.com/collections/resource (<span style="font-weight: bold;">right</span>)</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Do not use file extensions in URI’s</b></li>
<ul>
<li>http://api.url.com/collections/resource.txt (<span style="font-weight: bold;">wrong</span>)</li>
<li>http://api.url.com/collections/resource (<span style="font-weight: bold;">right</span>)</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Never use crud function names / type of URI (get/post/put/delete) in URI</b></li>
<ul>
<li>http://api.url.com/collections/get-resource (<span style="font-weight: bold;">wrong</span>)</li>
<li><b>GET</b> http://api.url.com/collections/resource (<span style="font-weight: bold;">right</span>)</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>Use query component to filter URI collection</b></li>
<ul>
<li>http://api.url.com/collections/resource?id=1&amp;order=2&amp;limit=10</li>
</ul>
</ul>
<div>
<br/>
</div>
</div>
<div>
<ul>
<li><b>When you have collection say named as inventory which contains many items within then you should use singular name/word to denote the entity.</b>
<br/>
</li>
<ul>
<li>http://api.example.com/<b>inventory/</b>clothes/{item-id}</li>
</ul>
</ul>
<div>
<br/>
</div>
<ul>
<li><b>When you’re accessing many records then plural naming rule should be implied</b>
<br/>
</li>
<ul>
<li>http://api.example.com/inventory/<b>clothes</b>/{item-id}</li>
</ul>
</ul>
<br/>
<ul>
<ul/>
<li><b>Do not create new api’s for reorder, sorting, filtering use query parameter send options as value in query payload</b>
<br/>
</li>
<ul>
<li><a href="http://api.example.com/inventory/">http://api.example.com/inventory/</a><a href="http://api.example.com/inventory/">clothes</a>/items?order=1&amp;limit=10</li>
</ul>
</ul>
</div>
<div>
<br/>
</div>
</body>
</html>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment