API Versioning as a Translation Layer
API versioning as an architecture: requests enter through a version header, pass through a chain of reversible version changes, and reach controllers that only ever see the latest model.
Loading…
Topic
API
76 posts about API. Every summary links to the original.
- 76 posts
- 24 companies
- 8 explainers
See the idea
API explainers
The API Gateway Boundary: Where Protocol, Policy, and Protection Meet
The API gateway is the single boundary where protocol translation, auth, quotas, and routing become shared policy instead of per-service code. This layered diagram shows what belongs there and why.
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
Newest first
Posts
What are MCP Servers?
This explainer clarifies what Model Context Protocol (MCP) servers do and where they differ from conventional APIs, serverless functions, and standalone appliances. It frames MCP servers as Alexa Skills that connect capabilities to an LLM, then as JSON-based APIs with multiplexing, server push, and built-in introspection for discovering tools, arguments, and usage descriptions. The post cautions that blindly generating an MCP server from an OpenAPI schema may expose low-level calls rather than agent-oriented workflows, and notes that MCP servers have a long-lived initialization, operation, and shutdown lifecycle rather than a serverless one. It also argues that MCP is not inherently secure or private, recommending remotely hosted servers protected by revocable bearer tokens, and envisions customized MCP-based agents becoming family-like assistants rather than mere appliances.
How to Add the Moesif API Observability Add-On to Your Heroku Applications
Heroku applications can add the Moesif API Observability add-on to analyze API traffic and support monetization. The setup uses either the Heroku CLI or Dashboard: the CLI command is heroku addons:create moesif, while the UI path goes through Resources, Find more add-ons, and Metrics and Analytics. Provisioning creates a MOESIF_APPLICATION_ID config variable, and the application then requires the Moesif SDK initialized with that value. The guide also covers copying the variable into a local .env file with Heroku Local and excluding that file from Git through .gitignore. Once configured, API events should flow into Moesif for live logs, time-series metrics, funnels, retention, alerting, and billing features, while Heroku handles add-on billing and user management.
Behind the Scenes - A Glimpse into Tax Calculations
As jurisdictions increasingly require marketplaces to collect and remit tax, Etsy describes the infrastructure it uses to calculate, record, and report taxes on transactions. When a buyer adds an item to a cart, Etsy sends a Quotation Request API call to Vertex, using buyer and seller locations, product category, tax rules, and mappings to determine the amount shown. At checkout and throughout fulfillment, DistributeTaxRequest SOAP calls carry order, cancellation, and refund details to Vertex, whose records support reporting and audit workflows imported into Etsy’s bigdata. The integration also required mapping Etsy taxonomy categories to Vertex rule drivers and separating quotation, distribution, and reporting workloads across multiple instances for horizontal scaling and load balancing. Shadow requests, ramped gradually without applying calculated taxes to carts, let the team simulate added Vertex load and monitor checkout performance before releasing traffic-increasing features.
Mastering API Gateway Integration: Salesforce, Heroku, and MuleSoft Anypoint Flex Gateway
MuleSoft Anypoint Flex Gateway provides a pattern for exposing APIs and microservices running in Heroku Private Spaces while adding API management and security controls. The tutorial deploys an internal Heroku application, creates or imports an OpenAPI 3.0 specification in Anypoint Design Center, publishes it to Exchange, registers the gateway through Runtime Manager, and deploys it in the same Private Space. That placement lets internal-routing applications receive public traffic through the gateway while routing access through a centrally configured layer managed with MuleSoft and Heroku. It then applies a Client ID Enforcement policy in API Manager, showing that requests with incorrect credentials fail and requests using the issued Client ID and Client Secret can authenticate. The pattern is presented as a foundation for Heroku and Salesforce multi-cloud integrations.
Working with ChatGPT Functions on Heroku
Menu Maker is a Node.js web application that turns user-supplied ingredients into a dish name, fine-dining description, ingredient list, and recipe. Its React front end communicates with an Express back end, which adds prompt instructions and sends the request to OpenAI’s Chat Completions API. The application uses ChatGPT’s function calling feature to define an updateDish function with structured JSON fields for the title, description, ingredients, and recipe, so parsed arguments can update React state directly. The GitHub-hosted Node.js monorepo is deployed to Heroku, where an OPENAI_API_KEY config var authenticates requests, an optional CHATGPT_MODEL selects the model, and Heroku runs yarn build and yarn start.
Why You Should Migrate to OAuth 2.0 From Static API Tokens
Static API tokens provide a simple way to authorize calls to protected third-party APIs, but their long lifetimes, broad permissions, and lack of user context create security and auditing risks. OAuth 2.0 addresses these limitations through a centralized authorization server that issues short-lived access tokens, which clients send in the Authorization header with the Bearer scheme. The post describes Client Credentials for service-to-service interactions and explains that scopes can distinguish permissions such as okta.users.read and okta.users.write; other configurations support task-based automation and user access through web applications. Migration guidance recommends implementing new calls with OAuth 2.0, applying least privilege, testing expiration and error handling, and securing private keys and JWKS generation before production deployment.
Notion Acquires Automate.io for Enhanced Automation & Integration | Notion
Notion announced that it is acquiring Automate.io to strengthen its strategy of connecting Notion with the other tools and systems used in everyday work. Automate.io had spent five years building connectivity and integrations for more than 200 software tools, and Notion says the acquisition will support high-quality native integrations for teams and businesses as well as features for developers building on Notion. The company plans to continue working with platform partners including Zapier and IFTTT after launching its API earlier in the year, while expanding access to workflows and integrations. The deal also makes Hyderabad, India, Notion’s fifth office and its first engineering centre outside the United States, with plans to grow a technical team there over several years.
Extend Flows with Heroku Compute: An Event-Driven Pattern
The post presents an event-driven pattern for extending Salesforce Flow with custom business logic deployed as a Heroku app and exposed as an external service. It uses an OpenAPI specification to define the interface, generates a Node.js application stub, adapts it for Heroku with a Procfile and port configuration, and registers the API in Salesforce. Flow accesses the service through a Named Credential using basic HTTP authentication, while the Heroku app authorizes Salesforce access with a JWT account token and API token. The example begins with product retrieval and then adds a Get Inventory method that can read inventory and update the Salesforce Product object. A Platform Event can trigger a flow that calls this method, while programmers and low-code builders iterate against the shared API contract before completing their work independently.
Building a GraphQL API in JavaScript
GraphQL lets API clients specify the fields they need instead of accepting a server-defined response, reducing unnecessary payload and potentially combining data from multiple stores behind one endpoint. The tutorial builds a JavaScript/Node.js implementation by loading Schema Definition Language (SDL) with graphql-tools, defining Query, User, and Address types, and connecting fields to resolver functions. Resolvers receive field arguments and can use context for authorization, illustrated by restricting address access to the current user. It also recommends keeping business logic separate from resolvers and notes that GraphQL does not eliminate database performance, caching, logging, monitoring, or versioning concerns. The discussion presents GraphQL as useful for evolving, front-end-heavy applications, while warning that its single HTTP status code and schema versioning limitations can complicate error handling and breaking changes.
Saved by the Schema: Using JSON Schema to Document, Test, and Debug APIs
Heroku uses JSON Schema to define Platform API response structures, generate documentation, and validate endpoint behavior. A CI-invoked rake task detects schema changes and uses prmd to generate Markdown API reference material, while committee tests API responses with assert_schema_conform. Those tests exposed an edge case in Enterprise usage data: dyno values with many decimal places were parsed by Oj as BigDecimal and serialized as quoted strings, whereas integer and ordinary float values remained numbers. Heroku traced this behavior through MultiJson and configured Oj with bigdecimal_load: :float, because the endpoint had sufficient precision at 15 decimal places and its schema required a number. The conforming test then passed, confirming that the schema and generated documentation matched returned API values.
Handling Addresses from All Around the World
International address handling is difficult because countries and locales differ in field order, required fields, terminology, translations, and display conventions. Shopify models each address with fields such as names, address lines, zones, postal code, city, country code, and phone, then stores country-specific metadata in YAML-backed country data. A reusable format describes form and display order, allowing clients to reorder fields, prepopulate country and zone values, and add locale-specific characters such as Japan’s 〒 and 様. Label keys and translations handle terms such as province, prefecture, postcode, and pincode, while an API endpoint keeps applications synchronized and accepts locale information. The team also provides @shopify/address and higher-level components, while identifying caching as a remaining issue to reduce repeated network calls.
Shaping the Future of Payments in the Browser
Shopify tested whether the Payment Request API was ready for its merchants and buyers on supported browsers. The team defined checkout completion rate, time to purchase, drop-off, and qualitative checkout experience as success measures, then ran an A/B experiment with selected merchants and eligible buyers. The isolated Ruby app injected storefront JavaScript, checked eligibility and credit-card support, and routed buyers to either the regular checkout or a browser-provided payment sheet. The experiment recorded a 7% checkout conversion rate drop and a 60% drop at the payment sheet, although time to completion medians were promising. Shopify concluded Payment Request was not yet a good fit, while expecting greater familiarity, payment-sheet improvements, and third-party payment methods through Payment Handler API to help adoption.
Beyond Web and Worker: Evolution of the Modern Web App on Heroku
Over a decade, the standard Heroku web application has expanded from a web process, database, worker, and Redis queue into a broader architecture for web, mobile, data, and operational demands. The post connects this shift to snappier single-page experiences, native smartphone apps, APIs as integration surfaces, growing streaming data, increasing system complexity, and scale. Its proposed components include a content delivery network, API Gateway, Apache Kafka, object storage, data warehouses, and query or visualization tools, alongside service-oriented architecture and scalable-first design. The architecture separates functionality into smaller services for adaptability, while acknowledging that more components create more scaling and operational levers. It presents Heroku’s PaaS and managed services as a way to reduce that burden, then leaves deployment, communication, CI/CD, monitoring, and security as topics for follow-up posts.
Heroku CLI: Completing Autocomplete
Heroku CLI Autocomplete had to support a dynamic, plugin-based command set while completing values that often reside behind the Heroku API. Instead of static shell case statements, its cache builder iterates through installed commands and generates setters that supply command, flag, and value completions when the user presses Tab. A shim sourced from the user’s .bashrc or .zshrc limits profile changes, fails silently when unavailable, and permits updates without repeated edits. API-backed values are cached on disk, while oclif custom hooks invalidate or rebuild relevant caches after commands change data. The completion function also parses the partially entered command line to provide contextual results, such as add-on aliases for a specified app; the work is being incorporated into an oclif plugin.
Incident Preparation: Simulating Third-Party Downtime
Heroku’s help application depends on the Platform API for authentication, authorization, and user data, so it must remain available to agents and customers during platform incidents. The open-sourced api-maintenance-sim app tests this requirement by imitating an outage in which every request receives an HTTP 503 Service Unavailable response. After deploying the simulator, teams point the application under test to its hostname through PLATFORM_API_URL, passed to platform-api’s connect_oauth method; when unset, the gem uses the production URI. A heroku config:set command enables the alternate endpoint, making regular simulations possible and helping reveal what failure means for the application or service when the Platform API is unavailable, supporting preparation for incidents and communication during outages.
Introducing the Heroku HTTP API Toolkit
Heroku is open sourcing the toolchain it uses to design, document, and consume HTTP APIs, covering a design guide, JSON Schema tooling, and generated Ruby and Go clients. The guide addresses versioning, resource structure, naming, serialization, errors, request IDs, pagination, and caching, while prmd can bootstrap schemas, verify completeness, and generate documentation. JSON Schemas also drive client generation through Heroics for Ruby and Schematic for Go, with examples showing access to the Heroku Platform API and generation from its schema. Heroku says the toolkit supports both user-facing and internal services, where shared schemas and generated documentation provide a common language for proposing APIs or changes and help align design practices.
Related topics
All topics →Weekly digest
The best engineering reads, once a week.