add contents for REST API Headers, Security and Versioning

Author: anishmanandhar

docs/rest-api/headers.md

@@ -5,3 +5,20 @@ sidebar_label: Headers
 ---
 
 #### The following convention should be followed for REST API Headers
+
+* Headers names should be **noun**  and should be **Captialised-Case** separated by **(-)**. e.g  **Token-Key**, **Account-ID**, **Tenant-ID** etc
+
+* For cases like Acronym, use acronyms itself. eg. *PID-value*, *PIN*
+
+* Headers can be used for meta information that the API carries for e.g
+  * Authentication
+  * Authorization
+  * Versioning the API
+  * Content-Type
+  * Caching etc
+  * <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" target="_blank">More Examples</a>
+
+* Avoid using headers for business logic
+
+* Use headers for parameters that should not appear in the URL 
+  * for e.g https://api.application.com/users/{id}/fetch?apiKey=abcd123456789 //**BAD Practice**

docs/rest-api/security.md

@@ -4,4 +4,23 @@ title: Security Method
 sidebar_label: Security
 ---
 
-#### Security
+## Best Practices to Secure REST APIs
+
+### Always Use HTTPS
+
+* By always using SSL, the authentication credentials can be simplified to a randomly generated access token that is delivered in the username field of HTTP Basic Auth. It’s relatively simple to use, and you get a lot of security features for free.
+  
+* If you use HTTP 2, to improve performance – you can even send multiple requests over a single connection, that way you avoid the complete TCP and SSL handshake overhead on later requests.
+
+### Never expose information on URLs
+
+* Usernames, passwords, session tokens, and API keys should not appear in the URL, as this can be captured in web server logs, which makes them easily exploitable. e.g  
+ https://api.app.com/users/{id}/fetch?apiKey=abcd123456789  //Bad practice
+
+### Conside using token based authentication like OAUTH2
+
+### Consider Adding Timestamp in Request
+
+### Log each request and response data
+
+### Validate Incoming request

docs/rest-api/versioning.md

@@ -4,4 +4,32 @@ title: Versioning
 sidebar_label: Versioning
 ---
 
-#### The following convention should be followed for Versioning
+## Four common REST API versioning strategies
+
+### Versioning through URI Path (*recommended*)
+
+> <http://api.app.com/v1/products>
+>
+> One way to version a REST API is to include the version number in the URI path.This solution often uses URI routing to point to a specific version of the API. Because cache keys (in this situation URIs) are changed by version, clients can easily cache resources. When a new version of the REST API is released, it is perceived as a new entry in the cache.
+
+### Versioning through custom header
+
+> curl -H API-Version: 1.0” <http://api.app.com/products>
+>
+> This approach doesn’t clutter the URI with versioning information.
+
+### Versioning through query parameters
+
+> <http://api.app.com/products?version=1>
+>
+>Another option for versioning a REST API is to include the version number as a query parameter.
+
+### Versioning through content negotiation
+
+> curl -H “Accept: application/vnd.xm.device+json; version=1” <http://api.app.com/products>
+>
+>The last strategy we are addressing is versioning through content negotiation.
+>
+>This approach allows us to version a single resource representation instead of versioning the entire API which gives us a more granular control over versioning. It also creates a smaller footprint in the code base as we don’t have to fork the entire application when creating a new version. Another advantage of this approach is that it doesn’t require implementing URI routing rules introduced by versioning through the URI path.
+>
+>One of the drawbacks of this approach is that it is less accessible than URI-versioned APIs: Requiring HTTP headers with media types makes it more difficult to test and explore the API using a browser.