Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@apisyouwonthate/style-guide

Package Overview
Dependencies
Maintainers
1
Versions
19
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@apisyouwonthate/style-guide

Make your HTTP APIs better, faster, stronger, whether they are still being designed (API Design-First) or your organization has flopped various mismatched APIs into production and now you're thinking some consistency would be nice. Using Spectral and Open

  • 1.1.9
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
11K
decreased by-5.11%
Maintainers
1
Weekly downloads
 
Created
Source

APIs You Won't Hate: API Style Guide

Make your APIs "better" according to APIs You Won't Hate, with this slick command line tool that'll run on your OpenAPI.

Installation

npm install --save -D @apisyouwonthate/style-guide
npm install --save -D @stoplight/spectral-cli

Usage

Create a local ruleset that extends the style guide. In its most basic form this just tells Spectral what ruleset you want to use, but it will allow you to customise things, add your own rules, turn bits off if its causing trouble.

cd ~/src/<your-api>

echo 'extends: ["@apisyouwonthate/style-guide"]' > .spectral.yaml

If you're using VS Code or Stoplight Studio then the NPM modules will not be available. Instead you can use the CDN hosted version:

echo 'extends: ["https://unpkg.com/@apisyouwonthate/style-guide@1.1/dist/ruleset.js"]' > .spectral.yaml

Next, use Spectral CLI to lint against your OpenAPI description. Don't have any OpenAPI? Record some HTTP traffic to make OpenAPI and then you can switch to API Design-First going forwards.

spectral lint api/openapi.yaml

You should see some output like this, letting you know there are a few more standards you could be using (shoutout to Standards.REST):

/Users/phil/src/protect-earth-api/api/openapi.yaml
  18:7   warning  api-health               Creating a `/health` endpoint is a simple solution for pull-based monitoring and manually checking the status of an API.  paths
  18:7   warning  api-home                 Stop forcing all API consumers to visit documentation for basic interactions when the API could do that itself.           paths
  36:30  warning  no-unknown-error-format  Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc6648) or the JSON:API Error format.   paths./v1/orders.post.responses[401].content.application/json
  96:30  warning  no-unknown-error-format  Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc6648) or the JSON:API Error format.   paths./v1/orders/{order}.get.responses[401].content.application/json
 112:30  warning  no-unknown-error-format  Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc6648) or the JSON:API Error format.   paths./v1/orders/{order}.get.responses[404].content.application/json

Now you have some things to work on for your API. Thankfully these are only warnings, which are not going to fail continuous integration (unless you want them to).

Backstory

You could write your API Style Guide as a giant manifesto and hope people see it, or you could automate your API style guide using a tool like Spectral so that your API Style Guide is enforced at the pull request level. This is an integral part of any successful API Governance program, otherwise you're all just wasting time covering the basics far too late in the game.

Spectral runs on top of OpenAPI and AsyncAPI, powering linting in editors, as a CLI tool, in continuous integration, etc., and comes with its own set of baked in OpenAPI v2/v3 rules. Making rules about how to write OpenAPI can help beginners write better OpenAPI, but its real power is using rules to make the actual APIs better and more consistent, before there is any programming involved.

This NPM package brings together all sorts of advice found in the books and blog posts from APIs You Won't Hate books. If you apply this to APIs in production, this is basically Phil Sturgeon judging your API for free instead of doing paid consulting. But if you can get this API Style Guide involved in the API Design-First workflow, you're getting free advice on how to design a better API before you waste any time coding, which then means fewer backwards-compatibility breaks as you fix things.

There are a bunch of other rulesets you can check out if you feel like making your own API Style Guides, or feel like contributing some new rules here via a pull request.

🎉 Thanks

📜 License

This repository is licensed under the MIT license.

🌲 Sponsor

If you'd like to say thanks for this style guide, throw some money at Protect Earth, a charity that plants trees all over the United Kingdom, which has secured a 64 acre ancient woodland to restore. Phil spends all his time on this, both planting trees and writing APIs believe it or not!

Keywords

FAQs

Package last updated on 11 Sep 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc