APIs¶

Uma API é um conjunto de protocolos, rotinas e ferramentas para criar aplicativos de software. Ele especifica como os componentes de software devem interagir.

Tipos de API:¶

• APIs públicas: abertas para uso por desenvolvedores externos (por exemplo, API do Twitter)
• APIs privadas: usadas internamente em uma organização
• APIs de parceiros: compartilhadas com parceiros de negócios específicos
• APIs compostas: combine várias APIs de dados ou serviços

Estilos de API¶

Os estilos de arquitetura definem como diferentes componentes de uma interface de programação de aplicativos (API) interagem uns com os outros. Como resultado, eles garantem eficiência, confiabilidade e facilidade de integração com outros sistemas, fornecendo uma abordagem padrão para projetar e criar APIs. Aqui estão os estilos mais usados:

• SOAP (Simple Object Access Protocol): Um protocolo para troca de dados estruturados. Maduro, abrangente, baseado em XML.
• RESTful (Representational State Transfer): um estilo de arquitetura amplamente usado para APIs da Web. Métodos HTTP populares e fáceis de implementar, sendo ideal para serviços da web.
• GraphQL: uma linguagem de consulta para APIs que permite que os clientes solicitem dados específicos.
• gRPC: uma estrutura de código aberto de alto desempenho desenvolvida pelo Google. Buffers de protocolo modernos e de alto desempenho, adequado para arquiteturas de microsserviços.
• WebSockets: Permite a comunicação full-duplex em tempo real entre o cliente e o servidor.Conexões persistentes, bidirecionais e em tempo real. Perfeito para troca de dados de baixa latência.
• Webhook: Permite notificações em tempo real e arquitetura orientada a eventos. Retornos de chamada HTTP orientados por eventos, assíncronos. Notifica os sistemas quando ocorrem eventos.

Segurança da API¶

• Autenticação: Básica, OAuth 2.0, JSON Web Tokens (JWT)
• Autorização: Controlando direitos de acesso a recursos
• Limitação de taxa: Prevenção de abusos limitando o número de solicitações
• Criptografia: Protegendo dados em trânsito usando HTTPS

Práticas recomendadas de design de API¶

• Convenções RESTful: Usando métodos HTTP corretamente, nomenclatura adequada de recursos
• Controle de versão: controle de versão de URI (por exemplo, /v1/users), controle de versão de parâmetro de consulta (por exemplo, /users?version=1), controle de versão de cabeçalho (por exemplo, Aceitar: application/vnd.company.v1+json).
• Paginação: Manipulação eficiente de grandes conjuntos de dados
• Tratamento de erros: uso adequado de códigos de status HTTP e mensagens de erro informativas

Documentação da API¶

• Especificação Swagger/OpenAPI: Um padrão para descrever APIs RESTful
• Postman: Uma ferramenta popular para desenvolvimento e documentação de API
• ReDoc: Uma ferramenta para gerar uma bela documentação de API

Teste de API¶

• Postman: Permite criar e executar testes de API
• SoapUI: Uma ferramenta para testar APIs SOAP e REST
• JMeter: Usado para testes de desempenho e carga
• API Mocking: Ferramentas como Mockoon ou servidores simulados do Postman para simular respostas de API

Gerenciamento de API¶

• Gateways de API: Azure API Management, AWS API Gateway, Kongk, Apigee.
• Gerenciamento do ciclo de vida: coleções de carteiros, RapidAPI, Akan.
• Análise e monitoramento de API: Moesif. Datadog, pilha ELK (Elasticsearch, Logstash, Kibana)

Regras¶

• no 1: Use substantivos plurais para coleções:É uma convenção arbitrária, mas está bem estabelecida e eu descobri que as violações tendem a ser um indicador principal de "esta API terá arestas".

  GET /products              # get all the products
  GET /products/{product_id} # get one product
  

• no 2: Não adicione segmentos de caminho desnecessários

  # GOOD
  GET /v3/application/listings/{listing_id}
  

• no 3: Não adicione .json ou outras extensões à url

API Security Checklist¶

Lista das mais importantes medidas de segurança para o desenvolvimento, teste e publicação da sua API.

Autenticação (Authentication)¶

• Não use Basic Auth. Use padrões de autenticação (exemplo: JWT, OAuth).
• Não reinvente a roda nos quesitos Autenticação, geração de tokens e armazenamento de senhas. Use os padrões recomendados para cada caso.
• Implemente funcionalidades de limite (Max Retry) e bloqueio de tentativas de autenticação.
• Use criptografia em todos os dados confidenciais.

JWT (JSON Web Token)¶

• Use uma chave de segurança aleatória e complicada (JWT Secret) para tornar ataques de força bruta menos eficientes.
• Não utilize o algoritmo de criptografia informado no cabeçalho do payload. Force o uso de um algoritmo específico no back-end (HS256 ou RS256).
• Defina o tempo de vida do token (TTL, RTTL) o menor possível.
• Não armazene informações confidenciais no JWT, pois elas podem ser facilmente decodificadas.
• Evite armazenar muitos dados. JWT geralmente é compartilhado em headers e eles têm um limite de tamanho.

Acesso (Access)¶

• Limite a quantidade de requisições (Throttling) para evitar ataques DDoS e de força bruta.
• Use HTTPS no seu servidor para evitar ataques MITM (Man In The Middle Attack).
• Use cabeçalho HSTS com SSL para evitar ataques SSL Strip.
• Desative as listagens de diretórios.
• Para APIs privadas, permita o acesso apenas de IPs/hosts da lista branca (whitelist).

Autorização (Authorization)¶

OAuth¶

• Sempre valide o redirect_uri no seu servidor através de uma lista de URLs conhecidas (previamente cadastradas).
• Tente sempre retornar códigos de negociação, não o token de acesso (não permita response_type=token).
• Utilize o parâmetro state com um hash aleatório para previnir CSRF no processo de autenticação OAuth.
• Defina escopo de dados, e valide o parâmetro scope para cada aplicação.

Requisição (Input)¶

• Utilize o método HTTP apropriado para cada operação, GET (obter), POST (criar), PUT/PATCH (trocar/atualizar) e DELETE (apagar).
• Valide o tipo de conteúdo informado no cabeçalho Accept da requisição (Content Negotiation) para permitir apenas os formatos suportados pela sua API (ex. application/xml, application/json ... etc), respondendo com o status 406 Not Acceptable se ele não for suportado.
• Valide o tipo de conteúdo do conteúdo da requisição informado no cabeçalho Content-Type da requisição para permitir apenas os formatos suportados pela sua API (ex. application/x-www-form-urlencoded, multipart/form-data, application/json ... etc).
• Valide o conteúdo da requisição para evitar as vulnerabilidades mais comuns (ex. XSS, SQL-Injection, Remote Code Execution ... etc).
• Não utilize nenhuma informação sensível (credenciais, senhas, tokens de autenticação) na URL. Use o cabeçalho Authorization da requisição.
• Use apenas criptografia do lado do servidor.
• Use um serviço gateway para a sua API para habilitar cache, limitar acessos sucessivos (ex. por quantidade máxima permitida (Quota), por limitar tráfego em situações de estresse (spike arrest) ou por limitar o número de conexões simultâneas na sua API (Concurrent Rate Limit)), e facilitar o deploy de novas funcionalidades.

Processamento (Processing)¶

• Verifique continuamente os endpoints protegidos por autenticação para evitar falhas na proteção de acesso aos dados.
• Não utilize a identificação do próprio usuário. Use /me/orders no lugar de /user/654321/orders.
• Não utilize ID's incrementais. Use UUID.
• Se você estiver processando arquivos XML, verifique que entity parsing não está ativada para evitar ataques de XML externo (XXE - XML external entity attack).
• Se você estiver processando arquivos XML, verifique que entity expansion não está ativada para evitar Billion Laughs/XML bomb através de ataques exponenciais de expansão de XML.
• Use CDN para uploads de arquivos.
• Se você estiver trabalhando com uma grande quantidade de dados, use workers e queues (fila de processos) para retornar uma resposta rapidamente e evitar o bloqueio de requisições HTTP.
• Não se esqueça de desativar o modo de depuração (DEBUG mode OFF).
• Use stacks não executáveis quando disponíveis.

Resposta (Output)¶

• Envie o cabeçalho X-Content-Type-Options: nosniff.
• Envie o cabeçalho X-Frame-Options: deny.
• Envie o cabeçalho Content-Security-Policy: default-src 'none'.
• Remova os cabeçalhos de identificação dos softwares do servidor - X-Powered-By, Server, X-AspNet-Version.
• Envie um cabeçalho Content-Type na sua resposta com o valor apropriado (ex. se você retorna um JSON, então envie um Content-Type: application/json).
• Não retorne dados sensíveis como senhas, credenciais e tokens de autenticação.
• Utilize o código de resposta apropriado para cada operação. Ex. 200 OK (respondido com sucesso), 201 Created (novo recurso criado), 400 Bad Request (requisição inválida), 401 Unauthorized (não autenticado), 405 Method Not Allowed (método HTTP não permitido) ... etc.

CI & CD¶

• Monitore a especificação e implementação do escopo da sua API através de testes unitários e de integração.
• Use um processo de revisão de código, ignorando sistemas de auto-aprovação.
• Certifique-se de que todos os componentes de seus serviços sejam validados por softwares AV (anti-vírus, anti-malware) antes de enviar para produção, incluindo as dependências de terceiros utilizadas.
• Execute continuamente testes de segurança (análise estática/dinâmica) em seu código.
• Verifique suas dependências (software e sistema operacional) para vulnerabilidades conhecidas.
• Implemente funcionalidade de reversão de deploy (rollback).

Monitoramento (Monitoring)¶

• Use logins centralizados para todos os serviços e componentes.
• Use agentes para monitorar todo o tráfego, erros, solicitações, e respostas.
• Use alertas para SMS, Slack, Email, Telegram, Kibana, Cloudwatch, etc.
• Verifique se você não está registrando dados confidenciais, como cartões de crédito, senhas, PINs, etc.
• Use um sistema IDS e/ou IPS para monitorar as solicitações e instâncias de sua API.

API Specification Languages¶

• OpenAPI (formerly known as Swagger)
• API Blueprint
• JSON Schema
• RAML

API Specification Tools¶

• Swagger Inspector: Test and auto-generate OpenAPI documentation for any API.
• Swagger Editor: An editor for designing Swagger specifications.
• Swagger Tools and Integrations: A list of libraries and frameworks serving the Swagger ecosystem.
• OpenAPI extension for VS Code: Visual Studio Code (VS Code) extension that provides support for the OpenAPI Specification.
• OpenAPI plugin for JetBrains IDEs: Jetbrains plugin that provides support for the OpenAPI Specification.
• Dredd: Validate API documentation written in API Blueprint against its backend implementation.
• API Spec Converter: Convert between different API spec formats.
• Apimatic: Supports API description formats including Swagger, OAI format, RAML, API Blueprint, IO Docs, WADL, Postman Collections and HAR 1.4 and more
• OpenAPI Definition Designer: Free visual OpenAPI3 definition creation and editing tool.
• Stoplight Studio: Create, prototype, and share OpenAPI descriptions and JSON Schemas using a visual editor.
• Spectral: Define rulesets to lint YAML or JSON, including OpenAPI 2.x, 3.x and AsyncAPI
• Optic: Verify the accuracy of your OpenAPI 3.x spec using real traffic, and automatically apply patches that keep it up-to-date
• RateMyOpenAPI: Open-source tools that scans your OpenAPI spec and identifies issues with documentation, security, and SDK generation - and generates a report with fix suggestions.
• OpenAPI DevTools: Browser extension that generates API specs for any app or website

API Specifications¶

• API Commons: A repository of language-agnostic API specifications / Data Models.
• APIS.guru: Directory of API specs in OpenAPI(aka Swagger) 2.0 format.
• AnyAPI: Documentation and Test Consoles for Public APIs.

API Frameworks¶

Ruby¶

• rails-api: Rails for API only applications.
• pliny: Opinionated template Sinatra app for writing APIs in Ruby.
• grape: An opinionated micro-framework for creating REST-like APIs in Ruby.
• ActiveModel::Serializer: Brings convention over configuration to your JSON generation.
• rabl: Generate JSON and XML from any ruby object.
• jbuilder: Create JSON structures via a Builder-style DSL.
• roar: Parse and render REST API documents using representers.

Python¶

• Django REST framework: Toolkit that makes it easy to build Web APIs.
• Tastypie: Webservice API framework for Django.
• restless: A lightweight REST miniframework for Python.
• flask-restful: Simple framework for creating REST APIs.
• Falcon: Falcon is a low-level, high-performance Python framework for building HTTP APIs, app backends, and higher-level frameworks.
• Connexion: Swagger/OpenAPI First framework for Python on top of Flask with automatic endpoint validation and OAuth2 support
• apistar: A smart Web API framework, designed for Python3.
• sanic: Sanic is a Flask-like Python 3.5+ web server that's written to go fast.
• hug: hug aims to make developing Python driven APIs as simple as possible, but no simpler.
• FastAPI: FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.

Javascript¶

• hapi.js: Web and services application framework for Node.js.
• Restify: Node.js REST framework specifically meant for web service APIs.
• Express: Fast, unopinionated, minimalist web framework for Node.js.
• sailsjs: Realtime MVC Framework for Node.js.
• Actionhero: Multi-transport Node.js API server with integrated cluster capabilities and delayed tasks.
• Baucis: To build
• Koa: Next generation web framework for Node.js
• Loopback: Node.js framework for creating APIs and easily connecting to backend data sources.
• Seneca: A microservices toolkit for Node.js.
• Feathers: Build RESTful and real-time APIs through Socket.io or Primus.
• Deployd: Deployd is the simplest way to build realtime APIs for web and mobile apps
• Nest: A modern node.js framework for efficient and scalable web applications built on top of TypeScript

Go¶

• Go-Json-Rest: Thin layer on top of net/http that helps building RESTful APIs easily
• gocrud: Go library to simplify creating, updating and deleting arbitrary depth structured data — to make building REST services fast and easy.
• sleepy: RESTful micro-framework written in Go.
• restit: Go micro framework to help writing RESTful API integration test.
• go-relax: Framework of pluggable components to build RESTful API's.
• go-rest: Small and evil REST framework for Go.
• go-restful: A declarative highly readable framework for building restful API's.
• Goat: Minimalistic REST API server in Go.
• Resoursea: REST framework for quickly writing resource based services.
• Zerver: Zerver is a expressive, modular, feature completed RESTful framework.
• Fiber: Fiber is an Express inspired web framework written in Go with .

Scala¶

• Colossus: I/O and microservice library for Scala.
• Finatra: Fast, testable, Scala HTTP services built on Twitter-Server and Finagle.
• Play: The high velocity web framework for Java and Scala.
• Scalatra: Simple, accessible and free web micro-framework.
• Skinny Micro: Micro-web framework to build servlet applications in Scala.
• Spray: Open-source toolkit for building REST/HTTP-based integration layers on top of Scala and Akka.
• Akka HTTP: The Akka HTTP modules implement a full server- and client-side HTTP stack on top of akka-actor and akka-stream.
• Swagger Akka HTTP: Swagger-Akka-Http brings Swagger support for Akka-Http Apis.

Java¶

• Rest.li: REST framework using type-safe bindings and asynchronous, non-blocking IO.
• Dropwizard: Framework for developing ops-friendly, high-performance, RESTful web services.
• Jersey: RESTful web services in Java.
• Spring Boot: RESTful Web Service using Spring, high-performance and little configuration needed.
• Metamug Mason: Create REST APIs with JSP tags and SQL. Edit and hot deploy REST resources on the server.

Haskell¶

• Scotty: Micro web framework inspired by Ruby's Sinatra, using WAI and Warp.
• Spock: Another Haskell web framework for rapid development.
• Servant: A Type-Level Web DSL.
• Yesod: The Haskell RESTful web framework.

Elixir¶

• Phoenix: Framework for building HTML5 apps, API backends and distributed systems.
• Plug: A specification and conveniences for composable modules between web applications.

Erlang¶

• Cowboy: Small, fast, modular HTTP server written in Erlang.
• Gen Microservice: This library solves the problem of implementing microservices with Erlang.
• Mochiweb: Erlang library for building lightweight HTTP servers.

Postgres¶

• PostgREST: Serve a RESTful API from any existing PostgreSQL database.
• pREST: pREST is a way to serve a RESTful API from any databases written in Go.

MySQL¶

• xmysql: Generate REST APIs for any MySQL Database.

PHP¶

• API Platform: API framework on top of Symfony with JSON-LD, Schema.org and Hydra support
• Dingo API: A RESTful API package for the Laravel and Lumen frameworks
• Fractal: Fractal provides a presentation and transformation layer for complex data output, the like found in RESTful APIs, and works really well with JSON
• Yii2 Framework: Provides a whole set of tools to simplify the task of implementing RESTful Web Service APIs

R¶

• Plumber: API Framework to build APIs for simple R Functions

C¶

• ASP.NET Web APIs: Build secure REST APIs on any platform with C#

Miscellaneous¶

• Dream Factory: Turn any database into an API platform.

API Client Development Tools¶

General¶

• Swagger CodeGen: Generate client libraries automatically from a Swagger-compliant server.
• AutoRest: Generate client libraries for RESTful web services
• OpenAPI Generator: A community fork of Swagger Codegen to automatically generate API clients, server stubs and documentation for REST APIs given an OpenAPI/Swagger spec.

Ruby¶

• Net::HTTP: An HTTP client API for Ruby.
• faraday: Simple, but flexible HTTP client library, with support for multiple backends.
• rest-client: Simple HTTP and REST client for Ruby
• heroics: Ruby HTTP client for APIs represented with JSON schema.
• blanket: A Ruby API wrapper.
• nestful: Ruby HTTP/REST client.

Java¶

• Retrofit: A type-safe HTTP client for Android and Java.

Javascript¶

• Restangular: Restangular is an AngularJS service that simplifies common GET, POST, DELETE, and UPDATE requests with a minimum of client code

.NET¶

• Refit: The automatic type-safe REST library for .NET Core, Xamarin and .NET
• WebAnchor: Web Anchor provides type-safe, testable and flexible access to web resources.

.Dart¶

• Frog: Dart Frog is built on top of shelf and mason and is inspired by many tools including remix.run, next.js, and express.js.
• Serverpod: Serverpod is a next-generation app and web server, built for the Flutter community. It allows you to write your server-side code in Dart, automatically generate your APIs, and hook up your database with minimal effort. Serverpod is open-source, and you can host your server anywhere.

API Documentation¶

• ReDoc: OpenAPI/Swagger-generated API Reference Documentation.
• Swagger UI: Dynamically generate documentation from a Swagger-compliant API.
• Slate: Static site generated documentation for your API.
• DeveloperHub: Documentation tool to write, publish, review, analyse and collect feedback on personalised customer-facing API docs.
• prmd: JSON Schema tooling: scaffold, verify, and generate documentation from JSON Schema documents.
• Aglio: An API Blueprint renderer with theme support that outputs static HTML.
• Apiary: Collaborative design, instant API mock, generated documentation, integrated code samples, debugging and automated testing.
• Readme: API Documentation Hosting.
• API Docs: Hosted public API documentation for OAS (Swagger) and RAML specs.
• Docbox: REST API documentation generator, using Markdown.
• widdershins: REST API documentation generator from OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0 definition
• Elements: Web Components-based API documentation for OpenAPI 3.x/2.x

API Clients¶

Open Source¶

• Hoppscotch: API client for REST, GraphQL, Websocket, SSE, Socket.IO and MQTT
• Hurl: Hurl makes it easy to work with HTML content, REST / SOAP / GraphQL APIs, or any other XML / JSON based APIs.
• ATAC: A feature-full TUI API client made in Rust. ATAC is free, open-source, offline and account-less.

Hosted¶

Desktop¶

API Debugging and Mocking¶

Hosted¶

Desktop¶

API Design Guides¶

API Publishing¶

API Gateways¶

API Security¶

API Web Scanners¶

API Monitoring¶

API Testing¶

API Developer Portal¶

JSON Format Standards¶

Learning Resources¶

Blogs¶

References¶

Contributing¶

Please write a brief one-sentence summary when adding a new resource.

Thanks¶

api-development-tools © 2016+, Yos Riady. Released under the MIT License.
Authored and maintained by Yos Riady with help from contributors (list).

• yos.io  · 
• GitHub @yosriady