add api design section

README.md

@@ -11,6 +11,7 @@
 - [Structure and Naming](#structure)
 - [Code style](#code_style)
 - [Logging](#logging)
+- [Api Design](#api)
 - [Licensing](#licensing)
 
 ## 1. Git
@@ -133,7 +134,146 @@ If less known dependency is needed,  discuss it with the team before using it.
 * Avoid client side console logs in production
 * Produce readable production logging. Ideally use production logging libraries to be used in production mode.
 
-## 10. Licensing
+
+## 10 Api design
+### 10.1 Follow Resource oriented design
+This has three main factors Resources, collection and URLs.
+* A resource has data, relationships to other resources, and methods that operate against it
+* A group of resources is called a collection.
+* URL identifies the online location of a resource.
+
+
+### 10.1 Naming
+
+#### 10.1.1 Naming URLs
+* `/users` a collection of users  (plural nouns)
+* `/users/id` a resource with information about a specific user   
+* A resource always should be plural in the url. Keeping verbs out of your resource URLs.
+* Use verb for non-resources. In this case, your API doesn’t return any resources. Instead, you execute an operation and return the result to the client. Hence, you should use verbs instead of nouns in your URL to distinguish clearly the non-resource responses from the resource-related responses.
+
+GET 	`/translate?text=Hallo`
+
+#### 10.1.2 Naming fields
+* The request body or response type is JSON then please follow `camelCase` to maintain the consistency. 
+* Use field labels for resource properties instead of using the same name as data base fields, You can adapt your existing fields to a changed or evolving database without introducing breaking changes. 
+* Only use nouns in your url naming and don’t try to explain their functionality and only explain the resources (elegantly).
+
+
+### 10.2 Operating on resources
+
+#### 10.2.1 Use HTTP methods
+Only use nouns in your resource URLs, avoid endpoints like `/addNewUser` or `/updateUser` .  Also avoid sending resource operations as a parameter. Instead explain the functionalities using HTTP methods:
+
+* **GET**		Used to retrieve a representation of a resource.
+* **POST**	Used to create new new resources and sub-resources
+* **PUT**		Used to update existing resources
+* **PATCH**	Used to update existing resources.  PATCH only updates the fields that were supplied, leaving the others alone
+* **DELETE**	Used to delete existing resources
+
+### 10.3 Use sub-resources
+Sub resources are used to link one resource with another, so use sub resources to represent the relation.
+If there is a relation between resources like  employee to a company, use `id` in the url:
+
+* **GET**		`/schools/2/students	`	Should get the list of all students from school 2
+* **GET**		`/schools/2/students/31`	Should get the details of student 31, which belongs to school 2
+* **DELETE**	`/schools/2/students/31`	Should delete student 31, which belongs to school 2
+* **PUT**		`/schools/2/students/31`	Should update info of student 31, Use PUT on resource-url only, not collection
+* **POST**	`/schools `					Should create a new school and return the details of the new school created. Use POST on collection-URLs
+
+### 10.4 Versioning 
+When your APIs are public other third parties, upgrading the APIs with some breaking change would also lead to breaking the existing products or services using your APIs. Using versions in your url can prevent that from happening:
+`http://api.domain.com/v1/schools/3/students	`
+
+### 10.5 Send feedbacks
+#### 10.5.1 Errors
+Response messages must be self descriptive. A good error message response might look something like this:
+```
+{
+“code”: 1234,
+“message” : “Something bad happened“,
+“description” : “More details”
+}
+```
+
+Note: Keep security  exception messages as generic as possible. For instance, Instead of saying ‘incorrect password’, you can reply back saying ‘invalid username or password’ so that we don’t unknowingly inform user that username was indeed correct and only password was incorrect.
+
+#### 10.5.2 Align your feedback with HTTP codes. 
+##### The client and API worked (success – 2xx response code)  
+* `200` HTTP response representing success for GET, PUT or POST.
+* `201` Created This status code should be returned whenever the new instance is created. E.g on creating a new instance, using POST method, should always return `201` status code.
+* `204` No Content represents the request is successfully processed, but has not returned any content. DELETE can be a good example of this. If there is any error, then the response code would be not be of 2xx Success Category but around 4xx Client Error category.
+
+##### The client application behaved incorrectly (client error – 4xx response code)
+* `400` Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
+* `401` Unauthorised indicates that the client is not allowed to access resources, and should re-request with the required credentials.
+* `403` Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any reason.
+* `404` Not Found indicates that the requested resource is not available now.
+* `406` Not Acceptable response. A lack of Content-Type header or an unexpected Content-Type header should result in the server rejecting the content
+* `410` Gone indicates that the requested resource is no longer available which has been intentionally moved.
+
+##### The API behaved incorrectly (server error – 5xx response code)
+* `500` Internal Server Error indicates that the request is valid, but the server is totally confused and the server is asked to serve some unexpected condition.
+* `503` Service Unavailable indicates that the server is down or unavailable to receive and process the request. Mostly if the server is undergoing maintenance.
+
+
+### 10.6 Resource parameters and metadata
+* Provide total numbers of resources in your response
+* The amount of data the resource exposes should also be taken into account.
+* Pagination, filtering and sorting don’t need to be supported by default for all resources. Document those resources that offer filtering and sorting.
+
+
+### 10.7 Security 
+#### 10.7.1 TLS
+To secure your web API authentication, all authentications should use SSL. OAuth2 requires the authorisation server and access token credentials to use TLS.
+Switching between HTTP and HTTPS introduces security weaknesses and best practice is to use TLS by default for all communication.
+
+#### 10.7.2 Rate limiting
+If your api is public or have high number of users, any client may be able to call your api thousands of times per hour. You should consider implementing rate limit early on.
+
+#### 10.7.3 Input Validation
+It's difficult to perform most attacks if the only allowed values are true or false, or a number, or one of a small number of acceptable values. 
+
+#### 10.7.4 URL validations
+Attackers can tamper with any part of an HTTP request, including the url, query string,
+
+#### 10.7.5 Validate incoming content-types.
+The server should never assume the Content-Type. A lack of Content-Type header or an unexpected Content-Type header should result in the server rejecting the content with a 406 Not Acceptable response.
+
+#### 10.7.6 JSON encoding
+A key concern with JSON encoders is preventing arbitrary JavaScript remote code execution within the browser or node.js, on the server.Use a JSON serialiser to encode user-supplied data properly to prevent the execution of user input on the browser/server.
+
+
+### 10.8 Document your api
+* There is a `Api Reference` section in Hive’s README.md template for api documentation
+* Describe api authentication methods with a code sample
+* explaining The URL Structure (path only, no root url) including The request type (Method) 
+* URL Params If URL params exist, specify them in accordance with name mentioned in URL section. Separate the section into Optional and Required.
+```
+Required: id=[integer]
+Optional: photo_id=[alphanumeric]
+Data Params: If the request type is POST, what should be the body payload look like? URL Params rules apply here too.
+```
+
+* Success Response, What should be the status code and is there any return data? This is useful when people need to know what their callbacks should expect!
+```
+Code: 200
+Content: { id : 12 }
+```
+
+* Error Response, Most endpoints have many ways to fail. From unauthorised access, to wrongful parameters etc. All of those should be listed here. It might seem repetitive, but it helps prevent assumptions from being made. For example 
+
+```
+"Code": 403
+"message" : "Authentication failed",
+"description" : "Invalid username or password"
+```
+
+
+#### 10.8.1 Tools
+There are lots of open source tools for good documentation like [API Blueprint | API Blueprint](https://apiblueprint.org/), Swagger , ENUNCIATE and Miredot, which enable client and documentation systems to update at the same pace as the server.
+
+
+## 11. Licensing
 Make sure you use resources that you have the rights to use. Copyrighted images and videos, for example, could cause legal problems.