CONTRIBUTING.md

Contributing
to govinfo-link-js

We welcome contributors, issues, and pull requests.

Contributions start with community conversations that lead to positive change. govinfo-link-js's open source collaboration model has five steps:

1. Issues

Start community conversations that determine whether proposed changes add value and should be made.

2. Pull Requests (PRs)

Inform and manage community code reviews for approved changes in-progress.

3. Merges

Incorporate approved PR changes into the product.

4. Releases

Make changes available for community consumption.

5. Support

Improves the product with refactorings and defect fixes.

Table of contents

• 1. Issues
  • 1.1. Create Issues for feature requests and defects.
  • 1.2. Format titles with (): .
  • 1.3. Fill out the issue template.
  • 1.4. Label the issue (optional).
  • 1.5. Monitor your issue for questions.
  • 1.6. Your issue will be either accepted for work, or declined.
• 2. Git
  • 2.1. Rules
    • 2.1.1. Makes changes in a topic branch.
    • 2.1.2. Favor the topic branch naming recommendation type/issue-change-name.
    • 2.1.3. Branch out from master.
    • 2.1.4. Never push into the master branch. Always submit a Pull Request.
    • 2.1.5. Submit a Pull Request as soon as possible.
    • 2.1.6. Rebase your local master branch before you ask for PR approvals.
    • 2.1.7. Resolve rebase conflicts before Pull Request reviews.
    • 2.1.8. Add reviewers and the label Status: Needs Review when the topic branch is ready.
    • 2.1.9. Delete local and remote topic branches after merging.
    • 2.1.10. Protect your master branch.
  • 2.2. Feature-branch-workflow
    • 2.2.1. Initialize a Git repository in the product directory (for new repositories only).
    • 2.2.2. Checkout a new feature or fix branch.
    • 2.2.3. Make Changes.
    • 2.2.4. Follow the Conventional Commits Specification for commit messages.
    • 2.2.5. Sync with remote to get changes you’ve missed.
    • 2.2.6. Update your topic branch with the latest changes from master by interactive rebase.
    • 2.2.7. Resolve conflicts (if any occur), and continue rebase.
    • 2.2.8. Push your branch with the -f flag (if necessary).
    • 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.
    • 2.3.1. Explain that inner and open source are process models.
    • 2.3.2. Describe a typical Git workflow in collaborative terms.
• 3. Code standards
  • 3.1. Use the Standard JS Style.
  • 3.2. Use ESLint to analyze source code.
• 4. Unit testing
  • 4.1. Write Mocha specifications (BDD tests).
  • 4.2. Reach 100% code coverage.
• 5. Directory structure
• 6. Logging
• 7. Dependencies
• 8. APIs
  • 8.1 API design
  • 8.2 API security
  • 8.3 API documentation
• 9. Licensing

1. Issues

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

  View govinfo-link-js's collaboration and contribution flowcharts:

  ---

Toggle view of the Issue workflow flowchart.

---

Toggle view of the Pull Request workflow flowchart.

---

• 1.1. Create Issues for feature requests and defects.

  Why:

  ⌦ govinfo-link-js 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 (): .

  govinfo-link-js follows the Conventional Commit Message specification, where:

                                                        <dl>
  
                                                      <dt>type</dt>
  
                                                    <dd><code>type</code> signifies the "kind of" change.</dd>
  
                                                  <dt>scope</dt>
  
                                                <dd><code>scope</code> covers the things being changed.</dd>
  
                                              <dt>subject</dt>
  
                                            <dd><code>subject</code> a succint summary/description (like a good e-mail subject).</dd>
  
                                        </dl>
  

  Why:

  This convention creates structred content that humans and machines can easily parse.

  Valid <types>:

                                                        <blockquote>
  
                                                    <dl>
  
                                                  <dt>
                                                  <a name="feat"></a>feat</dt>
  
                                                <dd>A new feature</dd>
  
                                              <!-- definition -->
  
                                              <dt>
                                              <a name="fix"></a>fix</dt>
  
                                            <dd>A bug fix
  
                                          </dd>
  
                                        <!-- definition -->
  
                                        <dt>
                                        <a name="docs"></a>docs</dt>
  
                                      <dd>Documentation only changes</dd>
  
                                    <!-- definition -->
  
                                    <dt>
                                    <a name="style"></a>style</dt>
  
                                  <dd>Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)</dd>
  
                                <!-- definition -->
  
                                <dt>
                                <a name="refactor"></a>refactor</dt>
  
                              <dd>A code change that neither fixes a bug nor adds a feature</dd>
  
                            <!-- definition -->
  
                            <dt>
                            <a name="perf"></a>perf</dt>
  
                          <dd>A code change that improves performance</dd>
  
                        <!-- definition -->
  
                        <dt>
                        <a name="test"></a>test</dt>
  
                      <dd>Adding missing tests or correcting existing tests</dd>
  
                    <!-- definition -->
  
                    <dt>
                    <a name="build"></a>build</dt>
  
                  <dd>Changes that affect the build system or external dependencies (example scopes: `gulp`, `broccoli`, `npm`)</dd>
  
                <!-- definition -->
  
                <dt>
                <a name="ci"></a>ci</dt>
  
              <dd>Changes to our CI configuration files and scripts (example scopes: `travis`, `circle`, `browser-stack`, `sauce-labs`)</dd>
  
            <!-- definition -->
  
            <dt>
            <a name="chore"></a>chore</dt>
  
          <dd>Other changes that don't modify src or test files</dd>
  
        <!-- definition -->
  
        <dt>
        <a name="revert"></a>revert</dt>
  
      <dd>Reverts a previous commit</dd>
  
  </dl>
  

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

• 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

• 2.1. Rules

  govinfo-link-js 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 govinfo-link-js team uses:

  • Feature-branch-workflow for small-ish codebases, or
  • Gitflow Workflow for large applications and monoliths

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

• 2.1.3. Branch out from master.

  Why:

  ⌦ govinfo-link-js 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

  • GitHub protected branches and
  • Bitbucket protected branches.

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

• 3.1. Use the Standard JS Style.

  govinfo-link-js 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

4. Unit testing

• 4.1. Write Mocha specifications (BDD 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
    
    CodeOfFederalRegulations
      cfrFetchUsingGET
        ✓ should call cfrFetchUsingGET successfully
    
    CompilationOfPresidentialDocuments
      cpdDcpdFetchUsingGET
        ✓ should call cpdDcpdFetchUsingGET successfully
      cpdFetchUsingGET
        ✓ should call cpdFetchUsingGET successfully
    
    CongressionalBills
      billsFetchUsingGET
        ✓ should call billsFetchUsingGET successfully
    
    CongressionalCalendars
      ccalFetchUsingGET
        ✓ should call ccalFetchUsingGET successfully
    
    CongressionalCommitteePrints
      cprtHouseFetchUsingGET
        ✓ should call cprtHouseFetchUsingGET successfully
      cprtJacketFetchUsingGET
        ✓ should call cprtJacketFetchUsingGET successfully
      cprtSenateFetchUsingGET
        ✓ should call cprtSenateFetchUsingGET successfully
    
    CongressionalDocuments
      cdocFetchUsingGET
        ✓ should call cdocFetchUsingGET successfully
      cdocJacketFetchUsingGET
        ✓ should call cdocJacketFetchUsingGET successfully
    
    CongressionalHearings
      chrgHouseFetchUsingGET
        ✓ should call chrgHouseFetchUsingGET successfully
      chrgJacketFetchUsingGET
        ✓ should call chrgJacketFetchUsingGET successfully
      chrgSenateFetchUsingGET
        ✓ should call chrgSenateFetchUsingGET successfully
    
    CongressionalRecordDaily
      crecSectionFetchUsingGET
        ✓ should call crecSectionFetchUsingGET successfully
      crecTypeFetchUsingGET
        ✓ should call crecTypeFetchUsingGET successfully
      crecTypeFetchUsingGET1
        ✓ should call crecTypeFetchUsingGET1 successfully
      crecVolumeFetchUsingGET
        ✓ should call crecVolumeFetchUsingGET successfully
    
    CongressionalReports
      crptBillFetchUsingGET
        ✓ should call crptBillFetchUsingGET successfully
      crptReportFetchUsingGET
        ✓ should call crptReportFetchUsingGET successfully
    
    FederalRegister
      frDocFetchUsingGET
        ✓ should call frDocFetchUsingGET successfully
      frVolumeFetchUsingGET
        ✓ should call frVolumeFetchUsingGET successfully
    
    PublicAndPrivateLaws
      plawBillFetchUsingGET
        ✓ should call plawBillFetchUsingGET successfully
      plawStatuteFetchUsingGET
        ✓ should call plawStatuteFetchUsingGET successfully
      plawTypeFetchUsingGET
        ✓ should call plawTypeFetchUsingGET successfully
    
    StatutesAtLarge
      statuteTypeFetchUsingGET
        ✓ should call statuteTypeFetchUsingGET successfully
      statuteVolumeFetchUsingGET
        ✓ should call statuteVolumeFetchUsingGET successfully
    
    UnitedStatesCode
      uscodeFetchUsingGET
        ✓ should call uscodeFetchUsingGET successfully
    
    27 passing (25ms)

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

5. Directory structure

node_modules has been excluded for brevity.

.
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── README.md
├── appveyor.yml
├── docs
│   ├── CodeOfFederalRegulations.md
│   ├── CompilationOfPresidentialDocuments.md
│   ├── CongressionalBills.md
│   ├── CongressionalCalendars.md
│   ├── CongressionalCommitteePrints.md
│   ├── CongressionalDocuments.md
│   ├── CongressionalHearings.md
│   ├── CongressionalRecordDaily.md
│   ├── CongressionalReports.md
│   ├── FederalRegister.md
│   ├── PublicAndPrivateLaws.md
│   ├── README.md
│   ├── StatutesAtLarge.md
│   ├── UnitedStatesCode.md
│   ├── common-vocabulary.md
│   ├── swagger.json
│   └── swagger.yaml
├── git_push.sh
├── node_modules/**
├── package-lock.json
├── package.json
├── src
│   ├── ApiClient.js
│   ├── api
│   │   ├── CodeOfFederalRegulations.js
│   │   ├── CompilationOfPresidentialDocuments.js
│   │   ├── CongressionalBills.js
│   │   ├── CongressionalCalendars.js
│   │   ├── CongressionalCommitteePrints.js
│   │   ├── CongressionalDocuments.js
│   │   ├── CongressionalHearings.js
│   │   ├── CongressionalRecordDaily.js
│   │   ├── CongressionalReports.js
│   │   ├── FederalRegister.js
│   │   ├── PublicAndPrivateLaws.js
│   │   ├── StatutesAtLarge.js
│   │   └── UnitedStatesCode.js
│   └── index.js
└── test
    └── api
        ├── CodeOfFederalRegulationsCFRApi.spec.js
        ├── CompilationOfPresidentialDocumentsCPDApi.spec.js
        ├── CongressionalBillsBILLSApi.spec.js
        ├── CongressionalCalendarsCCALApi.spec.js
        ├── CongressionalCommitteePrintsCPRTApi.spec.js
        ├── CongressionalDocumentsCDOCApi.spec.js
        ├── CongressionalHearingsCHRGApi.spec.js
        ├── CongressionalRecordDailyCRECApi.spec.js
        ├── CongressionalReportsCRPTApi.spec.js
        ├── FederalRegisterFRApi.spec.js
        ├── PublicAndPrivateLawsPLAWApi.spec.js
        ├── StatutesAtLargeSTATUTEApi.spec.js
        └── UnitedStatesCodeUSCODEApi.spec.js

2857 directories, 19904 files

6. Logging

govinfo-link-js uses bunyan for logging.

7. Dependencies

govinfo-link-js requires the following tech stack to either run, build, test, or deploy:

Dependency	Description	Version	License	Type
@semantic-release/[email protected]	Set of semantic-release plugins for creating or updating a changelog file	2.0.1	MIT	dev
@semantic-release/[email protected]	Set of semantic-release plugins to publish to a git repository	4.0.1	MIT	dev
@semantic-release/[email protected]	Set of semantic-release plugins to publish to a npm registry	3.2.2	MIT	dev
[email protected]	Another JSON Schema Validator	6.2.1	MIT	dev
[email protected]	Custom JSON-Schema keywords for Ajv validator	3.1.0	MIT	dev
[email protected]	Code Coverage reporter for Codacy.com	2.1.0	MIT	dev
[email protected]	Validates strings as commit messages	3.2.0	MIT	dev
[email protected]	takes json-cov output into stdin and POSTs to coveralls.io	3.0.0	BSD-2-Clause	dev
[email protected]	An AST-based pattern checker for JavaScript.	4.18.2	MIT	dev
eslint-config-prettier@^2.4.0	Turns off all rules that are unnecessary or might conflict with Prettier.	2.9.0	MIT	dev
[email protected]	umbrella config to get scanjs-like functionality from eslint	1.0.0-beta4	MPL-2.0	dev
[email protected]	JavaScript Standard Style - ESLint Shareable Config	11.0.0	MIT	dev
[email protected]	ESLint shareable config for XO	0.20.1	MIT	dev
[email protected]	Import with sanity.	2.9.0	MIT	dev
[email protected]	JSDoc linting rules for ESLint.	3.5.0	BSD-3-Clause	dev
[email protected]	Lint JSON files	1.2.0	ISC	dev
[email protected]	custom ESLint rule to disallows unsafe innerHTML, outerHTML and insertAdjacentHTML	1.0.16	MPL-2.0	dev
[email protected]	Additional ESLint's rules for Node.js	6.0.1	MIT	dev
eslint-plugin-prettier@^2.2.0	Runs prettier as an eslint rule	2.6.0	MIT	dev
[email protected]	Enforce best practices for JavaScript promises	3.7.0	ISC	dev
[email protected]	Security rules for eslint	1.4.0	Apache-2.0	dev
[email protected]	ESlint Plugin for the Standard Linter	3.0.1	MIT	dev
[email protected]	Various awesome ESLint rules	4.0.2	MIT	dev
[email protected]	Validates XSS related issues of mixing HTML and non-HTML content in variables.	0.1.9	ISC	dev
[email protected]	cli tool that cleans up package.json files.	2.3.1	MIT	dev
husky@^0.14.3	Prevents bad commit or push (git hooks, pre-commit/precommit, pre-push/prepush, post-merge/postmerge and all that stuff...)	0.14.3	MIT	dev
[email protected]	Delightful JavaScript Testing.	22.4.2	MIT	dev
[email protected]	An experimental ESLint runner for Mocha	0.4.0	MIT	dev
lec@^1.0.1	Command Line Wrapper for Line Ending Corrector (An utility that makes sure your files have consistent line endings)	1.0.1	MIT	dev
[email protected]	Lint files staged by git	7.0.0	MIT	dev
[email protected]	Automatically update markdown files with content from external sources	0.1.21	MIT	dev
[email protected]	Generate table of information about dependencies automatically in markdown	1.3.2	MIT	dev
[email protected]	Print install command for markdown file	1.3.1	MIT	dev
[email protected]	Print list of scripts in package.json with descriptions	1.2.1	MIT	dev
nsp@^3.2.1	The Node Security (nodesecurity.io) command line interface	3.2.1	Apache-2.0	dev
[email protected]	Prettier is an opinionated code formatter	1.11.1	MIT	dev
[email protected]	Automated semver compliant package publishing	15.0.2	MIT	dev

8. 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 Endpoints section in your README for programming interfaces.
  • 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

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.