Skip to content

Latest commit

 

History

History
1156 lines (890 loc) · 60.2 KB

CONTRIBUTING.md

File metadata and controls

1156 lines (890 loc) · 60.2 KB
Raw

Generator Community Repo

Contributing
to generator-community

PRs Welcome

Welcome to generator-community. You're among people eager to promote recommended community standards that encourage open source consumption and contributions with comprehensive README, CODE_OF_CONDUCT, CONTRIBUTING, and LICENSE documents. If you are curious, you're already a member!

Contributions start with community conversations that lead to positive change. Open source provides a flexible collaboration model that facilitates change, even among perfect strangers. Contributions therefore:

  1. Begin with Issues,
  2. Occur in Pull Requests, and
  3. End with Merges.

Table of contents

1. Issues

Issues

  • Collaboration starts with Issues. Changes happen through Pull Requests.

    View generator-community's collaboration and contribution flowcharts:

    Help Toggle view of the Issue workflow flowchart.

    Issue flowchart

    Help Toggle view of the Pull Request workflow flowchart.

    Pull Request flowchart

  • 1.1. Create Issues for feature requests and defects.

    Why:

    ⌦ generator-community follows an issue-driven product delivery model. Before any work is done, create an Issue, first. This starts a conversation about features, defects ("bugs"), refactoring, product delivery improvements, etc.

    Go ahead! Get started now:

  • 1.2. Format titles with type(scope): subject.

    Why:

    ⌦type categorizes product changes. Valid types are:

    • build: Changes that affect the build system or external dependencies.
    • ci: Changes related to continuous integration, delivery, and deployment tasks.
    • docs: Documentation changes.
    • feat: A new feature.
    • fix: Defect (bug) repair.
    • perf: Performance enhancements.
    • refactor: Source code design improvements that don't affect product behavior.
    • style: Changes involving graphics, typography, etc., as well as source code beautification.
    • test: Tests added to increase code coverage, or corrected due to errors.

  • 1.3. Fill out the issue template.

    Why:

    ⌦It keeps communication consistent and unambiguous.

  • 1.4. Label the issue (optional).

    Why:

    ⌦ We use git-labelmaker to categorize Issues (and Pull Requests) consistently. There are four label categories:

    • Type: the "kind" of product change.
    • Status: the state of a change.
    • Priority: the importance and value of a change.
    • Points: the size/complexity of a change.
    Help Toggle view of the Label definitions table.
    Label 🏷 Definition
    Type: Feature A distinguished or expected characteristic of a product that either differentiates the product from competitors, or whose absence would be diminish the product’s value.

    Note that Type: Feature and Type: Defect are mutually exclusive: an Issue cannot be both a feature and a defect.
    Type: Defect A flaw, fault, or abnormality that deviates from or prevents the product’s expected behavior.

    Note that Type: Feature and Type: Defect are mutually exclusive: an Issue cannot be both a feature and a defect.
    CLA: Signed The person who submitted a product change has signed your Contributor License Agreement.

    Remove this label if your product owner does not require a CLA.
    CLA: Unsigned The person who submitted a product change has __not__signed your Contributor License Agreement.

    Remove this label if your product owner does not require a CLA.
    Priority: Critical Type: Feature: The proposed enhancement is essential to the success of your product.

    Type: Defect: Your product no longer functions due to internal, FATAL errors, and must be addressed immediately in order to maintain consumer loyalty.
    Priority: High Type: Feature: The proposed enhancement is central to product’s value proposition, and should be implemented as soon as possible.

    Type: Defect: The product functions overall, but with an issue that risks consumer abandonment.
    Priority: Medium Type: Feature or Type: Defect: The proposed change should be implemented as long as no Priority: Critical or Priority: High issues exists.
    Priority: Low Type: Feature: A proposal that minimally affects the product’s value.

    Type: Defect: Represents “cosmetic” problems like misspelled words or misaligned text that do not affect branding and marketing strategy.
    Status: Abandoned Type: Feature or Type: Defect: The team and community have neglected, forgotten, discarded, or ignored resolving a Issue.
    Status: Accepted Type: Feature or Type: Defect: The product owner or maintainers agreed to a product change proposal.
    Status: Available Type: Feature and Type: Defect: The change proposal is ready for team and community members to work on.
    Status: Blocked Type: Feature and Type: Defect: The proposed change cannot be addressed until another issue has been resolved.

    Note that the Issue blocking the proposed change SHOULD be referenced in the Blocked Issue’s description field.
    Status: Completed Type: Feature and Type: Defect: The issue has been resolved and all acceptance criteria validated.
    Status: In Progress Type: Feature and Type: Defect: The team or community is actively working on the Issue’s resolution.
    Status: On Hold Type: Feature and Type: Defect: The Product Owner has (temporarily) postponed Issue resolution.

    Note that the reason for postponement should be stated in the Issue’s description field.
    Status: Pending Type: Feature and Type: Defect: product change or resolution is either awaiting the Product Owner’s decision. Ideally, the Product Owner should declare why they’re undecided somewhere in the Issue thread.
    Status: Rejected Type: Feature and Type: Defect: The Product Owner has declined a change proposal.

    Note that the Product Owner should politely explain why they dismissed the change request.
    Status: Review Needed Type: Feature and Type: Defect: The person working on an Issue has requested help or discussion. When applied to a Pull Request, Status: Review Needed signifies that the PR is ready for evaluation (and potentially, approval).
    Status: Revision Needed Type: Feature and Type: Defect: The Issue is not ready for evaluation because of incomplete or insufficient information.
    Type: Breaking Change The change introduces backward incompatibility with previous product versions.

    Type: Breaking Change MUST be recorded with a

    1. Git commit message,
    2. An increment (+1) in the product’s Semantic Version’s MAJOR version,
    3. CHANGELOG entry, and
    4. Updated API documentation.
    Type: Build Changes to the process that convert source code into a stand-alone form that can be run on a computer or to the form itself.
    Type: Chore Miscellaneous non-functional changes such as typographical fixes or source code repository initialization, e.g., chore(scm): scaffold product directory structure
    Type: CI Continuous Integration (CI) changes, i.e., automated build, test, an quality assurance tasks.
    Type: Docs The introduction of or revisions to natural language documents or source code comments.
    Type: Duplicate An Issue that shares the same characteristics as a previously reported issue.

    Note that product maintainers should reference the original Issue and close the Type: Duplicate Issue.
    Type: Feedback A response to a Type: Question or voluntary information used as a basis for improvement.
    Type: Fix A change intended to repair a Type: Defect Issue.
    Type: Performance A change intended to reduce product latency.
    Type: Question A request for information.
    Type: Refactor Source code design improvements that do not affect product behavior.
    Type: Revert Changes that return the product’s source code to previous Git commit hash.
    Type: Spike A technical or design experiment that investigates a possible solution.

    Note that spike solutions are, by definition, throwaway solutions that should NEVER be added to a product release.
    Type: Style Issues that address code standard or brand compliance.
    Type: Test Issues that prove intended behavior or substantiate “definitions of done.”

    Type: Test can also refer to changes that result in broader code coverage.

  • 1.5. Monitor your issue for questions.

    Why:

    ⌦ The team might need more clarification.

  • 1.6. Your issue will be either accepted for work, or declined.

    Why:

    ⌦ It's up to the Product Owner to agree to proposed changes. If they believe your issue add value, the issue will be approved, and we'll ask someone to volunteer to do the work.

    Otherwise, your issue will be politely declined.

2. Git

Git Logo

  • 2.1. Rules

    generator-community manages contributions with the feature-branch-workflow.

  • 2.1.1. Makes changes in a topic branch.

    Why:

    ⌦ Use an isolated topic branch for parallel product development. Topic branches allow you to submit multiple pull requests without confusion. You can iterate without polluting the master branch with potentially unstable, unfinished code. The generator-community team uses:

  • 2.1.2. Favor the topic branch naming recommendation type/issue-change-name.

    Why:

    ⌦ Although not required, our team prefixes branches with the type of change being introduced, followed by a forward slash and the issue id.

    Pattern: type/issueId-subject
    Icon legend: Bitbucket branch prefix Bitbucket GitHub branch prefix GitHub

    bugfix/
    Applies to Bitbucket branches Defect (bug) repair issues.
    build/
    Applies to GitHub branches Issues related to product builds.
    ci/
    Applies to GitHub branches Issues related to continuous integration, delivery, and deployment tasks.
    docs/
    Applies to GitHub branches Issues related to documentation.
    feat/
    Applies to GitHub branches New feature or enhancement requests.
    feature/
    Applies to Bitbucket branches New feature or enhancement requests.
    fix/
    Applies to GitHub branches Defect (bug) repair issues.
    Applies to Bitbucket branches `hotfix/`
    perf/
    Applies to GitHub branches Performance improvement issues.
    refactor/
    Applies to GitHub branches Source code design **improvements that do not affect product behavior**.
    revert/
    Applies to GitHub branches Tasks that revert to a previous commit hash.
    spike/
    Applies to GitHub branches Issues related in solution investigation.
    style/
    Applies to GitHub branches Issues related to style guideline compliance, especially `ESLint` errors and warnings.
    test/
    Applies to GitHub branches Test coverage tasks.

  • 2.1.3. Branch out from master.

    Why:

    ⌦ generator-community follows the feature-branch-workflow.

  • 2.1.4. Never push into the master branch. Always submit a Pull Request.

    Why:

    ⌦ It notifies team members whenever changes occur and allows the community to review your changes at any time..

    It also enables easy peer-review of the code and dedicates forum for discussing the proposed feature.

  • 2.1.5. Submit a Pull Request as soon as possible.

    Why:

    ⌦ Pull Requests declare work in progress. Frequent pushes to a Pull Request notify your team members about change, and gives them the opportunity to provide feedback more often.

    Pull Request pushes also trigger automated CI-services, which help you fail fast and assess quality.

  • 2.1.6. Rebase your local master branch before you ask for PR approvals.

    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). This results in a nice and clean history.

  • 2.1.7. Resolve rebase conflicts before Pull Request reviews.

    Why:

    ⌦ Rebasing will merge in the master branch and apply the commits that you have made locally to the top of it.

  • 2.1.8. Add reviewers and the label Status: Needs Review when the topic branch is ready.

    Why:

    ⌦ When you add a Reviewer, GitHub (or Bitbucket) notifies teammates that your topic branch meets all Acceptance Criteria and is ready to be merged into master.

    Add the label "Status: Review Needed" formally declares the status of your topic branch, and helps teams filter through issues.

  • 2.1.9. Delete local and remote topic branches after merging.

    Why:

    ⌦ Topic branches should only exist while work is in-progress. Merged topic branches clutter up your list of branches with dead branches. Topic branch deletion also insures that you only ever merge back into master.

  • 2.1.10. Protect your master branch.

    Why:

    ⌦ Branch protection prevents production-ready branches from incorporating unexpected and irreversible changes. Learn more about

  • 2.2. Feature-branch-workflow

    We use the feature-branch-workflow. We recommend interactive rebasing, too, but that's not required.

  • 2.2.1. Initialize a Git repository in the product directory (for new repositories only).

    For subsequent features and changes, this step should be ignored.

    cd <product-repo-directory>
git init

  • 2.2.2. Checkout a new feature or fix branch.

    # For a new feature branch:
git checkout -b feat/<issueId>-scope-of-change

# For branches that address defects:
git checkout -b fix/<issueId>-scope-of-change

  • 2.2.3. Make Changes.

    git add
git commit -a

    Why:

    ⌦ git commit -a will start an editor which lets you separate the subject from the body. Read more about it in section 1.3.

  • 2.2.4. Follow the Conventional Commits Specification for commit messages.

    This project enforces AngularJS Git Commit Guidelines (which is now an extension of the Conventional Commits Specfication) with commitplease pre-commit hooks.

    Why:

    Consistent, legible Git logs not only facilitate communication, but also enable automated CHANGELOG generation and semantic versioning with standard-version.

    • build commit messages

      Issues related to product builds.

      build(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • chore commit messages

      Issues related to miscellaneous non-functional changes (usually "maintenance" changes).

      chore(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • ci commit messages

      Issues related to continuous integration, delivery, and deployment tasks.

      ci(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • docs commit messages

      Issues related to documentation.

      docs(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • feat (feature) commit messages

      New feature or enhancement requests.

      feat(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • fix commit messages

      Defect (bug) repair issues.

      fix(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • perf (performance) commit messages

      Performance improvement issues.

      perf(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • refactor commit messages

      Source code design improvements that do not affect product behavior.

      refactor(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • revert commit messages

      Tasks that revert to a previous commit hash. Your message should begin with revert:, followed by the header of the reverted commit.

      In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

      revert: <hash>
<BLANK LINE>
This reverts commit <hash>.
<BLANK LINE>
<footer>

    • style commit messages

      Issues related to style guideline compliance, especially ESLint errors and warnings.

      style(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

    • test commit messages

      Test coverage tasks.

      test(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

  • 2.2.5. Sync with remote to get changes you’ve missed.

    git checkout master
git pull

    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.

  • 2.2.6. Update your topic branch with the latest changes from master by interactive rebase.

    git checkout <branchname>
git rebase -i --autosquash master

    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.

    Learn more about autosquashing Git commits.

  • 2.2.7. Resolve conflicts (if any occur), and continue rebase.

    git add <file1> <file2> ...
git rebase --continue

    Learn more about resolving conflicts.

  • 2.2.8. Push your branch with the -f flag (if necessary).

    Rebase changes history, so you might need to force changes into the remote branch with the -f flag. If someone else is working on your branch, use the less destructive --force-with-lease.

    git push -f

    Why:

    ⌦ When you do a rebase, you are changing the history on your topic branch. As a result, Git will reject normal git push. Instead, you'll need to use the -f or --force flag.

    Learn more about --force-with-lease.

  • 2.2.9. Submit a Pull Request.

  • 2.2.10. Once accepted, the Pull request will be merged, closed, and deleted by an administrator.

  • 2.2.11. Remove your local topic branch if you're done.

    git branch -d <branchname>

    to remove all branches which are no longer on remote

    git fetch -p && \
  for branch in `git branch -vv | grep ': gone]' | awk '{print $1}'`; \
    do git branch -D $branch; \
  done

2.3. Tell your boss how Git enables collaborative process models.

Leadership

  • Git enables collaboration with structured (business) process models. Git is a collaboration tool that grants people the opportunity to contribute to software products using simple and consistent process models called workflows.

    Help Toggle view of a workflow example.

    ⌦ Git is a collaboration tool that grants people the opportunity to contribute to software products using simple and consistent process models called _workflows_.

    1. Git __repositories__ store software products, as well as the historical changes to these products.

    2. Git workflows begin with either __cloning__ or __forking__ a repository, which __pulls__ a duplicate of the entire codebase onto a local computer.

    3. Contributors then create a local __topic branch__ in which they introduce changes—-features, fixes, documentation, tests, and design improvements—-which allows others to develop in parallel.

    4. Contributors __push__ their topic branch to others (usually another `remote` repository called `origin`) and submit __pull requests (PRs)__ to their announce their changes. __Pull requests are central to almost all Git workflows, since PRs allow Product Owners and their community to review suggested modifications. Product owners can approve or reject PRs at any time.__

    5. Other contributors answer the request to __pull__ the changes so they can review and test them.

    6. The changes in the PR are approved.

    7. The topic branch is either __merged__ or __rebased__ into the the software product.

    8. The topic branch gets deleted, and (ultimately) its changes are delivered to the world.

    Why:

    ⌦ Git can be intimidating, and The Boss (even if that's you!) needs to know why Git is valuable in business terms.

  • 2.3.1. Explain that inner and open source are process models.

    Why:

    ⌦ Git is a collaboration tool that grants people the opportunity to contribute to software products using simple and consistent process models called workflows.

  • 2.3.2. Describe a typical Git workflow in collaborative terms.

    Why:

    ⌦ Many engineers can discuss Git's technicalities, but cannot articulate Git's as an applied technology for collaboration.

3. Code standards

JavaScript Style Guide ESLint logo

  • 3.1. Use the Standard JS Style.

    generator-community follows the Standard JS Style.

  • 3.2. Use ESLint to analyze source code.

    Why:

    ⌦ ESLint evaluates JavaScript code (and --fixes what it can) whenever npm test runs. You can run ESLint directly with:

    npm run lint:js

    View generator-community's ESLint rules and their enforcement.

4. Unit testing

Jest JavaScript Testing

  • 4.1. Write Jest tests.

    Why:

    ⌦ Behavior-driven development specifications are executable documentation.

    • Put test files in the _test_ directory.

    • Use the .spec.js suffix for all tests.

  • 4.2. Reach 100% code coverage.

    Why:

    ⌦ Full coverage makes automated dependency drift updates safer.

    • View a test coverage summary in the Terminal:

      npm test

> jest --config=jest.config.json

  PASS  __tests__/app.js
   generator-community:app
    ✓ creates files (1ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        2.595s
Ran all test suites.
----------|----------|----------|----------|----------|----------------|
File      |  % Stmts | % Branch |  % Funcs |  % Lines |Uncovered Lines |
----------|----------|----------|----------|----------|----------------|
All files |      100 |      100 |      100 |      100 |                |
 index.js |      100 |      100 |      100 |      100 |                |
----------|----------|----------|----------|----------|----------------|

    • Open /coverage/lcov-report/index.html in a Web browser to view detailed coverage reports.

5. Directory structure

6. Logging

7. Dependencies

Package tech stack

StackShare

generator-community requires the following tech stack to either run, build, test, or deploy:

Dependency Description Version Type
[email protected] License generator for Yeoman based projects. 5.1.0 production
[email protected] Create a Node.js module 2.2.0 production
[email protected] Get the remote origin url of a git repository 2.0.0 production
[email protected] A high level git url parser for common git providers. 7.0.1 production
[email protected] Get a GitHub username from an email address 4.1.0 production
[email protected] Helper function using inquirer to validate a value provided in a prompt does not exist as an npm package. 2.0.0 production
lodash@^4.17.4 Lodash modular utilities. 4.17.4 production
[email protected] Automatically update markdown files with content from external sources 0.1.18 production
[email protected] Print install command for markdown file 1.3.1 production
[email protected] Print list of scripts in package.json with descriptions 1.2.0 production
[email protected] Parse an author, contributor, maintainer or other 'person' string into an object with name, email and url properties following npm conventions. 2.0.0 production
[email protected] Update notifications for your CLI app 2.2.0 production
[email protected] Rails-inspired generator system that provides scaffolding for your apps 2.0.0 production
[email protected] Jest plugin to use babel for transformation. 21.0.2 dev
[email protected] A Babel preset for each environment. 1.6.0 dev
[email protected] Babel browserify transform 7.3.0 dev
[email protected] Check installed versions of node and npm 2.1.0 dev
[email protected] Validates strings as commit messages 2.7.10 dev
coveralls@^2.13.1 takes json-cov output into stdin and POSTs to coveralls.io 2.13.1 dev
[email protected] An AST-based pattern checker for JavaScript. 4.7.2 dev
[email protected] ESLint shareable config for XO with 2-space indent 0.16.0 dev
[email protected] Import with sanity. 2.7.0 dev
[email protected] Eslint rules for Jest 21.1.0 dev
[email protected] JSDoc linting rules for ESLint. 3.1.3 dev
[email protected] custom ESLint rule to disallows unsafe innerHTML, outerHTML and insertAdjacentHTML 1.0.16 dev
[email protected] ESLint rule to disallow unsanitized code 2.0.1 dev
[email protected] Additional ESLint's rules for Node.js 5.1.1 dev
[email protected] Enforce best practices for JavaScript promises 3.5.0 dev
[email protected] ESLint plugin that contains ScanJS rules 0.2.1 dev
[email protected] Security rules for eslint 1.4.0 dev
[email protected] ESlint Plugin for the Standard Linter 3.0.1 dev
[email protected] Validates XSS related issues of mixing HTML and non-HTML content in variables. 0.1.8 dev
[email protected] cli tool that cleans up package.json files. 2.3.1 dev
[email protected] Delightful JavaScript Testing. 21.1.0 dev
[email protected] Delightful JavaScript Testing. 21.1.0 dev
[email protected] Generate a markdown TOC (table of contents) with Remarkable. 1.2.0 dev
[email protected] The Node Security (nodesecurity.io) command line interface 2.8.0 dev
[email protected] replacement for npm version with automatic CHANGELOG generation 4.2.0 dev
[email protected] Assert utility from yeoman 3.1.0 dev
[email protected] Test utilities for Yeoman generators 1.7.0 dev

8. APIs

APIs

  • 8.1 API design

    Why:

    ⌦ Because we try to enforce development of sanely constructed RESTful interfaces, which team members and clients can consume simply and consistently.

    Why:

    ⌦ Lack of consistency and simplicity can massively increase integration and maintenance costs. Which is why API design is included in this document.

    • We mostly follow resource-oriented design. It has three main factors: resources, collection, and URLs.

      • A resource has data, gets nested, and there are methods that operate against it.
      • A group of resources is called a collection.
      • URL identifies the online location of resource or collection.

      Why:

      ⌦ This is a very well-known design to developers (your main API consumers). Apart from readability and ease of use, it allows us to write generic libraries and connectors without even knowing what the API is about.

    • Use kebab-case for URLs.

    • Use camelCase for parameters in the query string or resource fields.

    • Use plural kebab-case for resource names in URLs.

    • Always use a plural nouns for naming a url pointing to a collection: /users.

      Why:

      ⌦ Basically, it reads better and keeps URLs consistent. read more...

    • In the source code convert plurals to variables and properties with a List suffix.

      Why:

      ⌦ Plural is nice in the URL but in the source code, it’s just too subtle and error-prone.

    • Always use a singular concept that starts with a collection and ends to an identifier:

      /students/245743
/airports/kjfk

    • Avoid URLs like this:

      GET /blogs/:blogId/posts/:postId/summary

      Why:

      ⌦ This is not pointing to a resource but to a property instead. You can pass the property as a parameter to trim your response.

    • Keep verbs out of your resource URLs.

      Why:

      ⌦ Because if you use a verb for each resource operation you soon will have a huge list of URLs and no consistent pattern which makes it difficult for developers to learn. Plus we use verbs for something else.

    • Use verbs for non-resources. In this case, your API doesn't return any resources. Instead, you execute an operation and return the result. These are not CRUD (create, retrieve, update, and delete) operations:

      /translate?text=Hallo

      Why:

      ⌦ Because for CRUD we use HTTP methods on resource or collection URLs. The verbs we were talking about are actually Controllers. You usually don't develop many of these. read more...

    • The request body or response type is JSON then please follow camelCase for JSON property names to maintain the consistency.

      Why:

      ⌦ This is a JavaScript project guideline, Where Programming language for generating JSON as well as Programming language for parsing JSON are assumed to be JavaScript.

    • Even though a resource is a singular concept that is similar to an object instance or database record, you should not use your table_name for a resource name and column_name resource property.

      Why:

      ⌦ Because your intention is to expose Resources, not your database schema details.

    • Again, only use nouns in your URL when naming your resources and don’t try to explain their functionality.

      Why:

      ⌦ Only use nouns in your resource URLs, avoid endpoints like /addNewUser or /updateUser . Also avoid sending resource operations as a parameter.

    • Explain the CRUD functionalities using HTTP methods:

      How:

      GET: Retrieve a representation of a resource.

      POST: Create new resources and sub-resources.

      PUT: Replace existing resources.

      PATCH: Update existing resources. It only updates the fields that were supplied, leaving the others alone.

      DELETE: Delete existing resources.

    • For nested resources, use the relation between them in the URL. For instance, using id to relate an employee to a company.

      Why:

      ⌦ This is a natural way to make resources explorable.

      How:

      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.

    • Use a simple ordinal number for a version with a v prefix (v1, v2). Move it all the way to the left in the URL so that it has the highest scope:

      http://api.domain.com/v1/schools/3/students

      Why:

      ⌦ 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. read more...

    • Response messages must be self-descriptive. A good error message response might look something like this:

      {
  "code"     : 404,
  "level"    : "ERROR",
  "logger"   : "[http-logger]",
  "message"  : "No resource found at URL /archetypes/v1/locales/iso-country-codes/BS",
  "timestamp": 1504878062000
}

      or for validation errors:

      {
  "code"     : 400,
  "logger"   : "[registration-form-logger]",
  "level"    : "ERROR",
  "timestamp": 1504878062000,
  "message"  :  "Validation Failed",
  "stack"    :[
    {
      "code"   : 1233,
      "field"  : "email",
      "message": "Invalid email"
    },
    {
      "code"   : 1234,
      "field"  : "password",
      "message": "No password provided"
    }
  ]
}

      Why:

      ⌦ Developers depend on well-designed errors at the critical times when they are troubleshooting and resolving issues after the applications they've built using your APIs are in the hands of their users.

      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 the password was incorrect.

    • Use only these 8 status codes to send with you response to describe whether everything worked, The client app did something wrong or The API did something wrong.

      Which ones:

      200 OK response represents success for GET, PUT or POST requests.

      201 Created for when new instance is created. Creating a new instance, using POST method returns 201 status code.

      304 Not Modified response is to minimize information transfer when the recipient already has cached representations.

      400 Bad Request for when the request was not processed, as the server could not understand what the client is asking for.

      401 Unauthorized for when the request lacks valid credentials and it should re-request with the required credentials.

      403 Forbidden means the server understood the request but refuses to authorize it.

      404 Not Found indicates that the requested resource was not found.

      500 Internal Server Error indicates that the request is valid, but the server could not fulfill it due to some unexpected condition.

      Why:

      ⌦ Most API providers use a small subset HTTP status codes. For example, the Google GData API uses only 10 status codes, Netflix uses 9, and Digg, only 8. Of course, these responses contain a body with additional information.There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to wikipedia to figure out what you're trying to tell them. read more...

    • Provide total numbers of resources in your response.

    • Accept limit and offset parameters.

    • 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:

      GET /student?fields=id,name,age,class

    • Pagination, filtering, and sorting don’t need to be supported from start for all resources. Document those resources that offer filtering and sorting.

  • 8.2 API security

    These are some basic security best practices:

    • Don't use basic authentication unless over a secure connection (HTTPS). Authentication tokens must not be transmitted in the URL: GET /users/123?token=asdf....

      Why:

      ⌦ Because Token, or user ID and password are passed over the network as clear text (it is base64 encoded, but base64 is a reversible encoding), the basic authentication scheme is not secure. read more...

    • Tokens must be transmitted using the Authorization header on every request: Authorization: Bearer xxxxxx, Extra yyyyy.

    • Authorization Code should be short-lived.

    • Reject any non-TLS requests by not responding to any HTTP request to avoid any insecure data exchange. Respond to HTTP requests by 403 Forbidden.

    • Consider using 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.

    • Setting HTTP headers appropriately can help to lock down and secure your web application. read more...

    • Your API should convert the received data to their canonical form or reject them. Return 400 Bad Request with details about any errors from bad or missing data.

    • All the data exchanged with the ReST API must be validated by the API.

    • Serialize your JSON.

      Why:

      ⌦ A key concern with JSON encoders is preventing arbitrary JavaScript remote code execution within the browser... or, if you're using node.js, on the server. It's vital that you use a proper JSON serializer to encode user-supplied data properly to prevent the execution of user-supplied input on the browser.

    • Validate the content-type and mostly use application/*json (Content-Type header).

      Why:

      ⌦ For instance, accepting the application/x-www-form-urlencoded mime type allows the attacker to create a form and trigger a simple POST request. 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 4XX response.

  • 8.3 API documentation

    • Fill the API Reference section in README.md template for API.
    • Describe API authentication methods with a code sample.
    • Explaining The URL Structure (path only, no root URL) including The request type (Method).

    For each endpoint explain:

    • URL Params If URL Params exist, specify them in accordance with name mentioned in URL section:

      Required: id=[integer]
Optional: photo_id=[alphanumeric]

    • If the request type is POST, provide working examples. URL Params rules apply here too. Separate the section into Optional and Required.

    • Success Responses. 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 Responses. Most endpoints have many ways to fail. From unauthorized 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:

      • HTTP status code

        404 Not Found

      • Response body

        {
  "code"     : 404,
  "level"    : "ERROR",
  "logger"   : "[http-logger]",
  "message"  : "No resource found at URL /archetypes/v1/locales/iso-country-codes/BS",
  "timestamp": 1504878062000
}

      • Response headers

        accept-ranges: bytes
access-control-allow-headers: Authorization
access-control-allow-methods: GET, HEAD, OPTIONS
access-control-allow-origin: *
cache-control: public, no-transform, must-revalidate
connection: keep-alive
content-encoding: gzip
content-language: en-US
content-length: 149
content-type: application/json
date: Fri, 08 Sep 2017 06:41:02 GMT
last-modified: Tue, 1 Oct 2014 10:10:10 GMT
server: nginx/1.12.1
vary: Accept-Encoding

    • Use API design tools, There are lots of open source tools for good documentation such as API Blueprint and Swagger.

9. Licensing

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 license details. Copyrighted images and videos may cause legal problems.