sthope/gitea_templates
Template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Reasoning improvements (#56)

Browse Source 
* Typo and grammar fix

* Add links

* Fix case inconsistency

* fix typo

* Fix grammar

* Fix grammar
This commit is contained in:
Vahid Panjganj 2017-07-12 12:16:26 +01:00 committed by GitHub
parent a2a6c1bbc5
commit 5706fe3734
1 changed files with 146 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
README.md
View File

@ -7,60 +7,76 @@
Here's a list of guidelines we've found, written and gathered that (we think) works really well with most JavaScript projects here at [hive](http://wearehive.co.uk).
If you want to share a best practice, or think one of these guidelines should be removed, [feel free to share it with us](http://makeapullrequest.com).
- [Git](#git)
- [Some Git rules](#some-git-rules)
- [Git workflow](#git-workflow)
- [Writing good commit messages](#writing-good-commit-messages)
- [Documentation](#documentation)
- [Environments](#environments)
- [Consistent dev environments](#consistent-dev-environments)
- [Consistent dependencies](#consistent-dependencies)
- [Dependencies](#dependencies)
- [Testing](#testing)
- [Structure and Naming](#structure-and-naming)
- [Code style](#code-style)
- [Logging](#logging)
- [API Design](#api-design)
- [API naming](#api-naming)
- [Operating on resources](#operating-on-resources)
- [Sub-resources](#aub-resources)
- [API versioning](#api-versioning)
- [API feedbacks](#api-feedbacks)
- [Resource parameters and metadata](#resource-parameters-and-metadata)
- [API security](#api-security)
- [API documentation](#api-documentation)
- [Licensing](#licensing)
## 1. Git <a name="git"></a>
### 1.1 Some Git Rules
<a name="git"></a>
## 1. Git
<a name="some-git-rules"></a>
### 1.1 Some Git rules
There are a set of rules to keep in mind:
* Perform work in a feature branch.
_why:_
_Why:_
>Because this way all work is done in isolation on a dedicated branch rather than the main branch. It allows you to submit multiple pull requests without confusion. You can iterate without polluting the master branch with potentially unstable, unfinished code. [read more...](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow)
* Branch out from `develop`
_why:_
_Why:_
>This way, you can make sure that code in master will almost always build without problems, and can be mostly used directly for releases (this might be overkill for some projects).
* Never push into `develop` or `master` branch. Make a Pull Request.
_why:_
_Why:_
> It notifies team members that they have completed a feature. It also enables easy peer-review of the code and dedicates forum for discussing the proposed feature
* Update your local `develop` branch and do a interactive rebase before pushing your feature and making a Pull Request
_why:_
_Why:_
> Rebasing will merge in the requested branch (`master` or `develop`) and apply the commits that you have made locally to the top of the history without creating a merge commit (assuming there were no conflicts). Resulting in a nice and clean history. [read more ...](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
* Resolve potential conflicts while rebasing and before making a Pull Request
* Delete local and remote feature branches after merging.
_why:_
_Why:_
> It will clutter up your list of branches with dead branches.It insures you only ever merge the branch back into (`master` or `develop`) once. Feature branches should only exist while the work is still in progress.
* Before making a Pull Request, make sure your feature branch builds successfully and passes all tests (including code style checks).
_why:_
_Why:_
> You are about to add your code to a stable branch. If your feature-branch tests fail, there is a high chance that your destination branch build will fail too. Additionaly you need to apply code style check before making a Pull Request. It aids readability and reduces the chance of formatting fixes being mingled in with actual changes.
* Use [this .gitignore file](./.gitignore).
_why:_
_Why:_
> It already has a list of system files that should not be sent with your code into remote repository. In addition, it excludes setting folders and files for mostly used editors, as well as most common dependency folders.
* Protect your `develop` and `master` branch .
_why:_
_Why:_
> It protects your production-ready branches from reciving unexpected and irreversible changes. read more... [Github](https://help.github.com/articles/about-protected-branches/) and [Bitbucket](https://confluence.atlassian.com/bitbucketserver/using-branch-permissions-776639807.html)
### 1.2 Git Workflow
<a name="git-workflow"></a>
### 1.2 Git workflow
Because of most of the reasons above, we use [Feature-branch-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow) with [Interactive Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing) and some elements of [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow) (naming and having a develop branch). The main steps are as follow:
* Checkout a new feature/bug-fix branch
@ -72,7 +88,7 @@ Because of most of the reasons above, we use [Feature-branch-workflow](https://w
git add
git commit -a
```
_why:_
_Why:_
> `git commit -a` will start an editor which lets your separate the subject from the body. Read more about it in *section 1.3*.
* Sync with remote to get changes you’ve missed
@ -81,7 +97,7 @@ Because of most of the reasons above, we use [Feature-branch-workflow](https://w
git pull
```
_why:_
_Why:_
> This will give you a chance to deal with conflicts on your machine while rebasing(later) rather than creating a Pull Request that contains conflicts.
* Update your feature branch with latest changes from develop by interactive rebase
@ -90,7 +106,7 @@ Because of most of the reasons above, we use [Feature-branch-workflow](https://w
git rebase -i --autosquash develop
```
_why:_
_Why:_
> You can use --autosquash to squash all your commits to a single commit. Nobody wants many commits for a single feature in develop branch [read more...](https://robots.thoughtbot.com/autosquashing-git-commits)
* If you don’t have conflict skip this step. If you have conflicts, [resolve them](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/) and continue rebase
@ -103,7 +119,7 @@ Because of most of the reasons above, we use [Feature-branch-workflow](https://w
git push -f
```
_why:_
_Why:_
> When you do a rebase, you are changing the history on your feature branch. As a result, Git will reject normal `git push`. Instead, you'll need to use the -f or --force flag. [read more...](https://developer.atlassian.com/blog/2015/04/force-with-lease/)
@ -111,24 +127,33 @@ Because of most of the reasons above, we use [Feature-branch-workflow](https://w
* Pull request will be accepted, merged and close by reviewer.
* Remove your local feature branch if you're done.
<a name="writing-good-commit-messages"></a>
### 1.3 Writing good commit messages
Having a good guideline for creating commits and sticking to it makes working with Git and collaborating with others a lot easier. Here are some rules of thumb ([source](https://chris.beams.io/posts/git-commit/#seven-rules)):
* **Separate the subject from the body with a newline between the two**
* Separate the subject from the body with a newline between the two
_why:_
> Having a `body` section lets you explain the context
that's useful for a code reviewer. if you can link to an associated Jira ticket, GitHub issue, Basecamp to-do, etc. Also most desktop Git clients have clear separation between message line and body in their GUI.
_Why:_
> Git is smart enough to distinguish the first line of your commit message as your summary. In fact, if you try git shortlog, instead of git log, you will see a long list of commit messages, consisting of the id of the commit, and the summary only
* Limit the subject line to 50 characters and Wrap the body at 72 characters
_why_
> Commits should be as fine-grained and focused as possible, it is not the place to be verbose. [read more...](https://medium.com/@preslavrachev/what-s-with-the-50-72-rule-8a906f61f09c)
* Limit the subject line to 50 characters
* Capitalize the subject line
* Do not end the subject line with a period
* Use [imperative mood](https://en.wikipedia.org/wiki/Imperative_mood) in the subject line
* Wrap the body at 72 characters
_Why:_
> Rather than writing messages that say what a committer has done. It's better to consider these messages as the instructions for what is going to be done after the commit is applied on the repository. [read more...](https://news.ycombinator.com/item?id=2079612)
* Use the body to explain **what** and **why** as opposed to **how**
## 2. Documentation <a name="documentation"></a>
<a name="documentation"></a>
## 2. Documentation
* Use this [template](./README.sample.md) for `README.md`, Feel free to add uncovered sections.
* For projects with more than one repository, provide links to them in their respective `README.md` files.
* Keep `README.md` updated as project evolves.
@ -138,16 +163,17 @@ that's useful for a code reviewer. if you can link to an associated Jira ticket,
* Don't use clean code as an excuse to not comment at all.
* Keep comments relevant as your code evolves.
## 3. Environments<a name="environments"></a>
* Depending on project size, define separate `development`, `test` and `production` environments.
<a name="environments"></a>
## 3. Environments
* Define separate `development`, `test` and `production` environments if needed.
_why:_
> Different data, tokens, APIs, ports etc... may be needed on different environments. You may want an isolated `development` mode that calls fake API which returns predictable data, making both automated and manually testing much easier. Or you may want to enable Google Analytics only on `production` and so on. [read more...](https://stackoverflow.com/questions/8332333/node-js-setting-up-environment-specific-configs-to-be-used-with-everyauth)
_Why:_
> Different data, tokens, APIs, ports etc... might be needed on different environments. You may want an isolated `development` mode that calls fake API which returns predictable data, making both automated and manually testing much easier. Or you may want to enable Google Analytics only on `production` and so on. [read more...](https://stackoverflow.com/questions/8332333/node-js-setting-up-environment-specific-configs-to-be-used-with-everyauth)
* Load your deployment specific configurations from environment variables and never add them to the codebase as constants, [look at this sample](./config.sample.js).
_why:_
_Why:_
> You have tokens, passwords and other valuable information in there. Your config should be correctly separated from the app internals as if the codebase could be made public at any moment.
_How:_
@ -156,68 +182,43 @@ that's useful for a code reviewer. if you can link to an associated Jira ticket,
* It’s recommended to validate environment variables before your app starts. [Look at this sample](./configWithTest.sample.js) using `joi` to validate provided values.
_why:_
_Why:_
> It may save others from hours of troubleshooting.
<a name="consistent-dev-environments"></a>
### 3.1 Consistent dev environments:
* Set your node version in `engines` in `package.json`
_why:_
_Why:_
> It lets others know the version of node the project works on. [read more...](https://docs.npmjs.com/files/package.json#engines)
* Additionally, use `nvm` and create a `.nvmrc` in your project root. Don't forget to mention it in the documentation
_why:_
_Why:_
> Any one who uses `nvm` can simply use `nvm use` to switch to the suitable node version. [read more...](https://github.com/creationix/nvm)
* You can also use a `preinstall` script that checks node and npm versions
* It's a good idea to setup a `preinstall` script that checks node and npm versions
_why:_
> Some dependencies may fail when used by newer versions of node.
_Why:_
> Some dependencies may fail when installed by newer versions of npm.
* Use Docker images provided it doesn't make things more complicated
* Use Docker image if you can.
_why:_
> It can give you a consistent environment across the entire workflow. Without much neeed to fiddle with libs, dependencies or configs. [read more...](https://hackernoon.com/how-to-dockerize-a-node-js-application-4fbab45a0c19)
_Why:_
> It can give you a consistent environment across the entire workflow. Without much need to fiddle with dependencies or configs. [read more...](https://hackernoon.com/how-to-dockerize-a-node-js-application-4fbab45a0c19)
* Use local modules instead of using globally installed modules
_why:_
> Lets you share your tooling with your colleague instead of expecting them to have it on their systems.
## 4. Dependencies <a name="dependencies"></a>
Before using a package, check its GitHub. Look for the number of open issues, daily downloads and number of contributors as well as the date the package was last updated.
* If less known dependency is needed, discuss it with the team before using it.
* Keep track of your currently available packages: e.g., `npm ls --depth=0`. [read more...](https://docs.npmjs.com/cli/ls)
* See if any of your packages have become unused or irrelevant: `depcheck`. [read more...](https://www.npmjs.com/package/depcheck)
_why:_
> The is a potential risk that you import this unused library in your bundle and ship it for production and as the result increase your bundle size. Find them, get rid of them.
* Check download statistics to see if the dependency is heavily used by the community: `npm-stat`. [read more...](https://npm-stat.com/)
_why:_
> More usage mostly means more contributors, which usually means better maintenance which results in bugs get discovered and fixed way quicker.
* Check to see if the dependency has a good, mature version release frequency with a large number of maintainers: e.g., `npm view async`. [read more...](https://docs.npmjs.com/cli/view)
_why:_
> Having loads of contributors wont be as effective, if maintainers dont merge those fixes and patches quickly enough.
* Always make sure your app works with the latest versions of dependencies without breaking: `npm outdated`. [read more...](https://docs.npmjs.com/cli/outdated)
_why:_
> Dependency updates sometimes have breaking changes, and you should be aware of that as quick as possible. Always check their release notes. Update your dependencies one by one, that makes troubleshooting easier (If breaking changes happens). Use cool tools such as [npm-check-updates](https://github.com/tjunnone/npm-check-updates).
* Check to see if the package has known security vulnerabilities with, e.g., [Snyk](https://snyk.io/test?utm_source=risingstack_blog).
_Why:_
> Lets you share your tooling with your colleague instead of expecting them to have it globally on their systems.
### 4.1 Consistent dependencies:
<a name="consistent-dependencies"></a>
### 3.2 Consistent dependencies:
* Make sure your team member gets the exact same dependencies as you
* Make sure your team members get the exact same dependencies as you
_why:_
_Why:_
> Because you want the code to behave as expected and identical in any development machine [read more...](https://medium.com/@kentcdodds/why-semver-ranges-are-literally-the-worst-817cdcb09277)
_how:_
@ -229,48 +230,78 @@ Before using a package, check its GitHub. Look for the number of open issues, da
_I don't like the name `Yarn`:_
> Too bad. For older versions of `npm`, use `—save --save-exact` when installing a new dependency and create `npm-shrinkwrap.json` before publishing. [read more...](https://docs.npmjs.com/files/package-locks)
<a name="dependencies"></a>
## 4. Dependencies
Before using a dependency, stalk it for a bit. Look for the number of open issues, daily downloads, number of contributors and date it was last updated.
## 5. Testing <a name="testing"></a>
* If less known dependency is needed, discuss it with the team before using it.
* Keep track of your currently available packages: e.g., `npm ls --depth=0`. [read more...](https://docs.npmjs.com/cli/ls)
* See if any of your packages have become unused or irrelevant: `depcheck`. [read more...](https://www.npmjs.com/package/depcheck)
_Why:_
> You may include an unused library in your code and increase the production bundle size. Find unused dependencies and get rid of them.
* Check download statistics to see if the dependency is heavily used by the community: `npm-stat`. [read more...](https://npm-stat.com/)
_Why:_
> More usage mostly means more contributors, which usually means better maintenance, and all of these result in quickly discovered bugs and quickly developed fixes.
* Check to see if the dependency has a good, mature version release frequency with a large number of maintainers: e.g., `npm view async`. [read more...](https://docs.npmjs.com/cli/view)
_Why:_
> Having loads of contributors wont be as effective, if maintainers dont merge fixes and patches quickly enough.
* Always make sure your app works with the latest versions of dependencies without breaking: `npm outdated`. [read more...](https://docs.npmjs.com/cli/outdated)
_Why:_
> Dependency updates sometimes contain breaking changes. Always check their release notes when updates show up. Update your dependencies one by one, that makes troubleshooting easier if anything goes wrong. Use a cool tool such as [npm-check-updates](https://github.com/tjunnone/npm-check-updates).
* Check to see if the package has known security vulnerabilities with, e.g., [Snyk](https://snyk.io/test?utm_source=risingstack_blog).
<a name="testing"></a>
## 5. Testing
* Have a `test` mode environment if needed.
_why:_
> Some believe for unit testing `development` mode and for end to end testing `production` mode will be enough. While this is partly true, there are some exceptions. One example is you may not want to enable analytical information on a 'production' mode and pollute someone's dashboard with test data. Or your API may apply rate limits in `production` and block your many test calls.
_Why:_
> While sometimes end to end testing in `production` mode might seem enough, there are some exceptions: One example is you may not want to enable analytical information on a 'production' mode and pollute someone's dashboard with test data. The other example is that your API may have rate limits in `production` and blocks your test calls after certain amount of requests.
* Place your test files next to the tested modules using `*.test.js` or `*.spec.js` naming convention, like `moduleName.spec.js`
_why:_
> You don't want to dig through a folder structure every time you have to find a unit test. Additionally, this naming convention is standard now and gets picked up by most JavaScript testing frameworks.
_Why:_
> You don't want to dig through a folder structure to find a unit test. [read more...](https://hackernoon.com/structure-your-javascript-code-for-testability-9bc93d9c72dc)
* Put your additional test files into a separate test folder to avoid confusion.
_why:_
_Why:_
> Some test files don't particularly relate to any specific implementation file. You have to put it in a folder that is most likely to be found by other developers: `__test__` folder. This name: `__test__` is also standard now and gets picked up by most JavaScript testing frameworks.
* Write testable code, avoid side effects, extract side effects, write pure functions
_why:_
_Why:_
> You want to test a business logic as a separate units. You have to "minimize the impact of randomness and non-deterministic processes on the reliability of your code". [read more...](https://medium.com/javascript-scene/tdd-the-rite-way-53c9b46f45e3)
* Don’t write tests to check types, instead use a static type checker
* Use a static type checker
_why:_
_Why:_
> Sometimes you may need a Static type checker. It brings a certain level of reliability to your code. [read more...](https://medium.freecodecamp.org/why-use-static-types-in-javascript-part-1-8382da1e0adb)
* Run tests locally before making any pull requests to `develop`.
_why:_
> Because you don't want to be the one who caused production-ready branch build to fail.
_Why:_
> You don't want to be the one who caused production-ready branch build to fail. Run your tests after your `rebase` and before pushing your feature-branch to remote repository.
* Document your tests, with instructions.
* Document your tests including instructions in the relevant section of your `README.md` file.
_why:_
_Why:_
> It's a handy note you leave behind for other developers or DevOps experts or QA or anyone who gets lucky enough to work on your code.
## 6. Structure and Naming <a name="structure-and-naming"></a>
<a name="structure-and-naming"></a>
## 6. Structure and Naming
* Organize your files around product features / pages / components, not roles. Also, place your test files next to their implementation.
@ -301,30 +332,30 @@ Before using a package, check its GitHub. Look for the number of open issues, da
| └── user.test.js
```
_why:_
_Why:_
> Instead of a long list of files, you will create small modules that encapsulate one responsibility including its test and so on. It gets much easier to navigate through and things can be found at a glance.
* Put your additional test files to a separate test folder to avoid confusion.
_why:_
_Why:_
> It is a time saver for other developers or DevOps experts in your team.
* Use a `./config` folder and don't make different config files for different environments.
_why:_
_Why:_
>When you break down a config file for different purposes (database, API and so on); putting them in a folder with a very recognizable name such as `config` makes sense. Just remember not to make different config files for different environments. It doesn't scale cleanly, as more deploys of the app are created, new environment names are necessary.
Values to be used in config files should provided by environment variables. [read more...](https://medium.com/@fedorHK/no-config-b3f1171eecd5)
* Put your scripts in a `./scripts` folder. This includes `bash` and `node` scripts.
_why:_
_Why:_
>It's very likely you may end up with more than one script, production build, development build, database feeders, database synchronisation and so on.
* Place your build output in a `./build` folder. Add `build/` to `.gitignore`.
_why:_
_Why:_
>Name it what you like, `dist` is also cool. But make sure that keep it consistent with your team. What gets in there is most likely generated (bundled, compiled, transpiled) or moved there. What you can generate, your teammates should be able to generate too, so there is no point commiting them into your remote repository. Unless you specifically want to.
* Use `PascalCase' 'camelCase` for filenames and directory names. Use `PascalCase` only for Components.
@ -333,18 +364,19 @@ Before using a package, check its GitHub. Look for the number of open issues, da
* Ideally the directory name should match the name of the default export of `index.js`.
_why:_
_Why:_
> Then you can expect what component or module you will receive by simply just importing its parent folder.
## 7. Code style <a name="code-style"></a>
<a name="code-style"></a>
## 7. Code style
* Use stage-2 and higher JavaScript (modern) syntax for new projects. For old project stay consistent with existing syntax unless you intend to modernise the project.
_why:_
_Why:_
> This is all up to you. We use transpilers to use advantages of new syntax. stage-2 is more likely to eventually become part of the spec with only minor revisions.
* Include code style check in your build process.
_why:_
_Why:_
> Breaking your build is one way of enforcing code style to your code. It prevents you from taking it less seriously. Do it for both client and server-side code. [read more...](https://www.robinwieruch.de/react-eslint-webpack-babel/)
* Use [ESLint - Pluggable JavaScript linter](http://eslint.org/) to enforce code style.
@ -400,7 +432,8 @@ Before using a package, check its GitHub. Look for the number of open issues, da
_Why:_
> It makes it more natural to read the source code.
## 8. Logging <a name="logging"></a>
<a name="logging"></a>
## 8. Logging
* Avoid client-side console logs in production
_Why:_
@ -412,7 +445,8 @@ Before using a package, check its GitHub. Look for the number of open issues, da
_Why:_
> It makes your troubleshooting less unpleasant with colorization, timestamps, log to a file in addition to the console or even logging to a file that rotates daily. [read more...](https://blog.risingstack.com/node-js-logging-tutorial/)
## 9 API design <a name="api-design"></a>
<a name="api-design"></a>
## 9 API design
* We mostly follow resource-oriented design. It has three main factors: resources, collection, and URLs.
* A resource has data, relationships to other resources, and methods that operate against it
@ -422,7 +456,8 @@ Before using a package, check its GitHub. Look for the number of open issues, da
_Why:_
> This is a very well-known design to developers (your main API audience). The core idea of REST is the resource and each resource is identified by a URL, and you retrieve that resource by sending a GET request to that URL. Very simple.
### 9.1 API Naming
<a name="api-naming"></a>
### 9.1 API naming
#### 9.1.1 Naming URLs
* `/users` a collection of users (plural nouns).
@ -446,7 +481,7 @@ GET `/translate?text=Hallo`
* Only use nouns in your URL when naming your resources and don’t try to explain their functionality.
<a name="operating-on-resources"></a>
### 9.2 Operating on resources
#### 9.2.1 Use HTTP methods
@ -458,7 +493,8 @@ Only use nouns in your resource URLs, avoid endpoints like `/addNewUser` or `/up
* **PATCH** Used to update existing resources. PATCH only updates the fields that were supplied, leaving the others alone
* **DELETE** Used to delete existing resources
### 9.3 Use sub-resources
<a name="Sub-resources"></a>
### 9.3 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
@ -467,14 +503,16 @@ Sub resources are used to link one resource with another, so use sub resources t
* **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
_why:_
_Why:_
>An API is supposed to be an interface for developers and this is a natural way to make resources explorable.
### 9.4 API Versioning
<a name="api-versioning"></a>
### 9.4 API versioning
When your APIs are public for 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 `
### 9.5 Send feedbacks
<a name="api-feedbacks"></a>
### 9.5 API feedbacks
#### 9.5.1 Errors
Response messages must be self descriptive. A good error message response might look something like this:
```json
@ -525,7 +563,7 @@ Note: Keep security exception messages as generic as possible. For instance, Ins
* `500 Internal Server Error` indicates that the request is valid, but the server could not fulfill it due to 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 or facing a temporary overload.
<a name="resource-parameters-and-metadata"></a>
### 9.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. The API consumer doesn't always need the full representation of a resource.Use a fields query parameter that takes a comma separated list of fields to include:
@ -534,14 +572,17 @@ Note: Keep security exception messages as generic as possible. For instance, Ins
```
* Pagination, filtering and sorting don’t need to be supported by default for all resources. Document those resources that offer filtering and sorting.
<a name="api-security"></a>
### 9.7 API security
#### 9.7.1 TLS
To secure your web API authentication, all authentications should use SSL. OAuth2 requires the authorization 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. Throw an error for non-secure access to API URLs.
#### 9.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.
If your API is public, you may want to consider Rate Limiting
_Why:_
> To protect your APIs from bot threats that call your API thousands of times per hour. You should consider implementing rate limit early on.
#### 9.7.3 Input Validation
It's difficult to perform most attacks if the allowed values are limited.
@ -560,7 +601,7 @@ The server should never assume the Content-Type. A lack of Content-Type header o
#### 9.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 entered data to prevent the execution of user input on the browser/server.
<a name="api-documentation"></a>
### 9.8 API documentation
* Fill the `API Reference` section in [README.md template](./README.sample.md) for API.
* Describe API authentication methods with a code sample
@ -591,7 +632,8 @@ Optional: photo_id=[alphanumeric]
#### 9.8.1 API design tools
There are lots of open source tools for good documentation such as [API Blueprint](https://apiblueprint.org/) and [Swagger](https://swagger.io/).
## 10. Licensing <a name="licensing"></a>
<a name="licensing"></a>
## 10. Licensing
Make sure you use resources that you have the rights to use. If you use libraries, remember to look for MIT, Apache or BSD but if you modify them, then take a look into licence details. Copyrighted images and videos may cause legal problems.