Recommended Free Tools
Build a public API as a product and an operating service—not just a set of endpoints. Start with the people and tasks it must support, define a versioned contract before implementation, then design security, limits, documentation, support, monitoring, and retirement into the service from the beginning.
1. Define who the API serves and what it exposes
Before choosing routes or frameworks, identify who will call the API, what jobs they need to complete, which data they are allowed to access, and where they can get help. Draw a clear boundary around the service: what it owns, what it reads from other systems, and what it will not expose.
The UK Government’s API technical and data standards, updated 30 September 2026, frame API work around user needs. Its guidance on managing APIs also treats team responsibilities and the service lifecycle as part of the work. Assign an owner who can make decisions about support, security, changes, and retirement; an API without an accountable operating team is an incomplete product.
- List the intended consumer types and the tasks each needs to perform.
- Decide which resources and actions each consumer is permitted to access.
- Identify the systems and dependencies behind the API, including any third-party services.
- Choose a support route and decide who handles incidents, access questions, and change notices.
2. Design the API contract before implementing it
Model the domain as resources, then define the operations consumers can perform on them, the parameters and representations involved, the expected status codes, validation rules, and authentication scheme. State what a successful response contains and what happens when a request is invalid, unauthorized, throttled, or affected by a dependency failure.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
The UK Home Office’s “Designing and Maintaining an API” guidance, updated 14 October 2024, requires an API specification and recommends versioning. For a REST API, OpenAPI 3 can describe endpoints, operations, parameters, and authentication methods. Treat that specification as the shared contract used by implementers, reviewers, and consumers—not as a substitute for the rest of the developer experience.
Keep the specification aligned with the deployed service. A contract that describes behavior the API does not actually provide is worse than incomplete documentation because consumers may build against false expectations.
3. Build the security model into every request path
Authentication establishes who or what is making a request; authorization determines whether that caller may perform this action on this specific resource and its properties. Apply authorization where the data or function is accessed. An unpredictable or hidden identifier is not a permission check.
Control access to objects, properties, and functions
OWASP’s API Security Top 10 for 2023 identifies broken object-level authorization, broken object-property authorization, and broken function-level authorization among major API risks. Check permissions for each requested object, constrain which fields callers may write, and avoid returning sensitive fields merely because the caller can access the object itself. Use explicit response schemas and allowlists for writable properties.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRank #2
Protect credentials and sensitive flows
OWASP also lists broken authentication and abuse of sensitive business flows. Choose authentication appropriate to the API’s consumers and risk, protect credentials in transit and storage, and consider whether actions such as account recovery, booking, or payment-related requests need additional safeguards against automated abuse. API keys can help identify callers and limit some forms of misuse, but OWASP’s REST Security Cheat Sheet cautions against relying on API keys alone for sensitive or critical resources.
Validate boundaries and maintain an inventory
Validate inputs and constrain resource-intensive operations. Treat data received from third-party APIs and webhooks as untrusted input. OWASP’s 2023 risk list also includes unrestricted resource consumption, server-side request forgery (SSRF), security misconfiguration, unsafe consumption of APIs, and improper inventory management. Keep an inventory of public hosts, deployed API versions, and non-production endpoints so abandoned or forgotten surfaces do not escape oversight.
NIST’s SP 800-228A, “Guidelines for the Secure Deployment of RESTful Web APIs,” was published as an initial public draft on 18 May 2026. It analyzes threats and controls across pre-runtime and runtime phases. It is a current reference to consider, but its draft status means it should not be represented as a final standard.
4. Make limits, errors, and pagination predictable
Consumers need to know how much they can request and what to do when they reach a limit. Document quotas per key or account, burst behavior, pagination or record caps, timeout expectations, error formats, and retry guidance. Specify whether a limit is shared across endpoints or applies separately, if that is how the service behaves.
The Home Office’s “Documenting an API,” updated 21 March 2025, says rate limits should be documented so consumers can design their software around them. Define throttling behavior explicitly and return HTTP 429 when requests are arriving too quickly, as recommended by OWASP’s REST Security Cheat Sheet. Explain how a client can recover rather than leaving it to guess whether and when to retry.
Limits are also a capacity and security control. They help constrain unrestricted resource consumption, but a limit that is invisible to consumers can cause avoidable failures. Set limits based on the service’s operating capacity and the legitimate tasks the API is intended to support.
5. Publish documentation that helps a developer succeed
An OpenAPI document makes the contract machine-readable, but it does not by itself explain how to become a successful consumer. GOV.UK’s guidance on describing RESTful APIs with OpenAPI 3 and the Home Office documentation standard point to the need for supporting usage information.
- Quick start: show the first useful call and the prerequisites to make it.
- Authentication: explain how consumers obtain and use credentials, including API-key instructions where applicable.
- Examples: provide representative requests and responses, plus sample applications when useful.
- Operational behavior: document quotas, pagination and record limits, timeout expectations, error responses, and retry guidance.
- Lifecycle and support: identify the current API version, its status, the change or migration process, and the route for help.
Keep examples consistent with the published contract and service behavior. A developer portal or documentation tool can help present this information, but tooling does not remove the need to decide what consumers must know.
6. Choose versioning and plan for change
Choose a versioning scheme before launch and make it visible to consumers. The Home Office design guidance requires a form of API versioning; possible approaches include placing the version in the URI, a query parameter, or a header. The important operational requirement is that consumers can identify which contract they are using and understand what changes affect it.
Classify changes by their effect on existing consumers. For a breaking change, publish what changes, which version is affected, the migration path, and the expected lifecycle dates or milestones. Avoid treating a new release as self-explanatory: consumers need a practical route from the old contract to the new one.
| Lifecycle status | What to communicate |
|---|---|
| Beta | That the version is not yet presented as stable, and what consumers should expect before relying on it. |
| Stable | That the version is the supported, published contract for consumers. |
| Deprecated | That consumers should plan migration, with the affected version and migration information identified. |
| Retired | That the version has reached the end of its lifecycle; make the successor or migration information clear where one exists. |
These lifecycle labels follow the statuses called out in GOV.UK API lifecycle guidance. Make the status of each version discoverable instead of expecting users to infer it from release dates or scattered announcements.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.7. Test and operate the API as a service
Before launch, test both the contract and the behaviors that protect it. Check authentication and authorization at object, property, and function levels; input validation; error and throttling responses; and behavior when dependencies fail. Test that published examples and documentation match the deployed API.
Best Value
Plan for scalability and resilience before traffic grows. Instrument latency, error rates, saturation, authentication failures, quota events, and dependency failures so the team can distinguish a client-side problem from an API or upstream incident. Keep the host and version inventory current, including non-production environments. The Home Office design guidance calls for observability, testing, scalability consideration, and security best practices as part of API design and maintenance.
8. Decide how the API will be evaluated and eventually retired
Review the API against the needs it was built to serve: can intended users complete their tasks, understand the contract, obtain support, and operate within published limits? For a platform or implementation comparison, assess contract quality and tooling, authentication and authorization controls, versioning and migration, quotas, error consistency, observability and inventory, scalability and resilience, onboarding, support, and total operating cost.
Retirement is part of the lifecycle, not an afterthought. Monitor whether a version is still needed, communicate deprecation and migration clearly, and make a deliberate decision about when it will stop being supported. GOV.UK guidance describes API management from publication to retirement; the team responsible for launch should also own those later decisions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
