http-api-design
HTTP API design guide extracted from work on the Heroku Platform API
Top Related Projects
Promise based HTTP client for the browser and node.js
🏊🏾 Simplified HTTP request client.
🌐 Human-friendly and powerful HTTP request library for Node.js
A light-weight module that brings the Fetch API to Node.js
Quick Overview
The interagent/http-api-design
repository is a guide for designing consistent, usable, and well-documented HTTP APIs. It provides a set of guidelines and best practices for API design, covering topics such as resource naming, HTTP verbs, response formats, and error handling.
Pros
- Comprehensive Guidelines: The repository offers a comprehensive set of guidelines and best practices for designing HTTP APIs, covering a wide range of topics.
- Community-Driven: The project is community-driven, with contributions from various developers and API experts, ensuring the guidelines are well-rounded and up-to-date.
- Vendor-Neutral: The guidelines are vendor-neutral, making them applicable to a wide range of API implementations and technologies.
- Promotes Consistency: By following the guidelines, developers can create more consistent and predictable APIs, improving the overall user experience.
Cons
- Opinionated: The guidelines presented in the repository are opinionated and may not align with the specific needs or preferences of all organizations or projects.
- Lack of Enforcement: The guidelines are not enforced, and it's up to individual developers or teams to adopt and implement them.
- Potential Outdated: As the API landscape evolves, some of the guidelines may become outdated or require updates over time.
- Lack of Tooling: The repository does not provide any specific tooling or automation to help enforce the guidelines, which may make it more challenging to adopt and maintain.
Getting Started
To get started with the interagent/http-api-design
guidelines, you can follow these steps:
- Clone the repository:
git clone https://github.com/interagent/http-api-design.git
-
Review the guidelines in the
README.md
file, which covers various aspects of HTTP API design, such as:- Resource Naming
- HTTP Verbs
- Response Formats
- Error Handling
- Authentication and Authorization
- Pagination and Filtering
- Versioning
-
Familiarize yourself with the guidelines and consider how they can be applied to your specific API design requirements.
-
Discuss the guidelines with your team and decide which ones to adopt or adapt based on your project's needs and constraints.
-
Incorporate the relevant guidelines into your API design process, ensuring consistency and adherence to best practices.
-
Continuously review and update your API design as the guidelines or your requirements evolve over time.
Remember, the interagent/http-api-design
repository is a community-driven guide, and you are encouraged to contribute your own experiences, feedback, or improvements to the guidelines.
Competitor Comparisons
Promise based HTTP client for the browser and node.js
Pros of axios/axios
- Provides a simple and consistent API for making HTTP requests, which can be more intuitive than the lower-level
interagent/http-api-design
approach. - Supports a wide range of features, including request and response transformations, interceptors, and cancellation.
- Has a large and active community, with extensive documentation and a wealth of third-party plugins and integrations.
Cons of axios/axios
- The library may be larger and more complex than necessary for some use cases, where a more lightweight solution like
interagent/http-api-design
might be more appropriate. - The API may be more opinionated and less flexible than the more low-level
interagent/http-api-design
approach, which allows for more customization.
Code Comparison
axios/axios:
axios.get('/user?ID=12345')
.then(function (response) {
console.log(response.data);
})
.catch(function (error) {
console.log(error);
});
interagent/http-api-design:
const http = require('http-api-design');
http.get('/user?ID=12345')
.then(response => {
console.log(response.body);
})
.catch(error => {
console.log(error);
});
🏊🏾 Simplified HTTP request client.
Pros of request/request
- Provides a simple and intuitive API for making HTTP requests, with support for a wide range of features such as cookies, headers, and query parameters.
- Has a large and active community, with many third-party libraries and plugins available to extend its functionality.
- Offers a consistent and well-documented API, making it easy to use and integrate into existing projects.
Cons of request/request
- May be less opinionated and structured than interagent/http-api-design, which provides a more comprehensive set of guidelines and best practices for building HTTP APIs.
- May not be as well-suited for building large-scale, enterprise-level HTTP APIs as interagent/http-api-design.
Code Comparison
request/request:
const request = require('request');
request.get('https://api.example.com/users', (error, response, body) => {
if (!error && response.statusCode === 200) {
console.log(body);
} else {
console.error(error);
}
});
interagent/http-api-design:
const http = require('http');
http.get('https://api.example.com/users', (res) => {
let data = '';
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
console.log(data);
});
}).on('error', (e) => {
console.error(e);
});
🌐 Human-friendly and powerful HTTP request library for Node.js
Pros of Got
- Got is a popular and widely-used HTTP client library for Node.js, with over 20,000 stars on GitHub.
- It provides a simple and intuitive API for making HTTP requests, with support for features like automatic JSON parsing, retries, and progress events.
- Got is actively maintained and has a large community of contributors, ensuring ongoing development and support.
Cons of Got
- Got is primarily focused on making HTTP requests, while HTTP API Design provides a more comprehensive set of guidelines and best practices for designing RESTful APIs.
- The documentation for Got may not be as extensive or detailed as the guidelines provided by HTTP API Design.
- Got is a client-side library, while HTTP API Design is more focused on server-side API design.
Code Comparison
Got:
const got = require('got');
got('https://api.example.com/data')
.then(response => {
console.log(response.body);
})
.catch(error => {
console.error(error);
});
HTTP API Design:
# HTTP API Design Guidelines
- Use nouns, not verbs, in endpoint URLs
- Use HTTP methods to indicate the type of operation
- Use a consistent naming convention for your endpoints
- Return appropriate HTTP status codes
- Use a consistent data format, such as JSON
- Provide clear and comprehensive documentation
A light-weight module that brings the Fetch API to Node.js
Pros of node-fetch/node-fetch
- Simplicity: node-fetch provides a straightforward and easy-to-use API for making HTTP requests in Node.js, without the need for additional dependencies.
- Cross-platform Compatibility: node-fetch is designed to work seamlessly across different platforms, including Windows, macOS, and Linux.
- Extensive Documentation: the project has comprehensive documentation, making it easy for developers to get started and understand the library's capabilities.
Cons of node-fetch/node-fetch
- Limited Functionality: compared to interagent/http-api-design, node-fetch may lack some advanced features and functionality for building complex HTTP APIs.
- Lack of Opinionated Design: node-fetch is a relatively low-level library, and it may require more boilerplate code to implement certain patterns or conventions.
Code Comparison
Here's a brief code comparison between node-fetch and interagent/http-api-design:
node-fetch:
const fetch = require('node-fetch');
fetch('https://api.example.com/data')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));
interagent/http-api-design:
const api = require('http-api-design');
api.get('/data')
.then(response => console.log(response.body))
.catch(error => console.error(error));
The interagent/http-api-design example demonstrates a more opinionated and higher-level API, which may provide more structure and conventions for building HTTP APIs.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
HTTP API Design Guide
This guide describes a set of HTTP+JSON API design practices, originally extracted from work on the Heroku Platform API.
This guide informs additions to that API and also guides new internal APIs at Heroku. We hope itâs also of interest to API designers outside of Heroku.
Our goals here are consistency and focusing on business logic while avoiding design bikeshedding. Weâre looking for a good, consistent, well-documented way to design APIs, not necessarily the only/ideal way.
We assume youâre familiar with the basics of HTTP+JSON APIs and wonât cover all of the fundamentals of those in this guide.
Available for online reading and in multiple formats at gitbook.
We welcome contributions to this guide.
See Summary for Table of Contents.
For the best reading experience, we recommend reading via GitBook.
Gitbook Translations
- English
- Italian (based on f12db3e), by @diegomariani
- Simplified Chinese (based on 40d114b), by @ZhangBohan
Git Translations
- Korean (based on f38dba6), by @yoondo
- Portuguese (based on fba98f08b5), by @Gutem
- Simplified Chinese (based on 337c4a0), by @ZhangBohan
- Spanish (based on 2a74f45), by @jmnavarro
- Traditional Chinese (based on 232f8dc), by @kcyeu
- Turkish (based on c03842f), by @hkulekci
Top Related Projects
Promise based HTTP client for the browser and node.js
🏊🏾 Simplified HTTP request client.
🌐 Human-friendly and powerful HTTP request library for Node.js
A light-weight module that brings the Fetch API to Node.js
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot