APIs with a written contract
Each API comes with a written contract, such as an OpenAPI description (a standard format for describing an HTTP API). It sets out each operation, who may call it and what each caller is told.
API development and integration services in India
APIs that connect your systems — with the access rules written down.
We build documented APIs and connect the systems you already run. The API contract (the written rulebook for your API) sets out who may call it, which records each caller may reach, and what a caller is told when a record isn't theirs.
- Access rules written into the contract
- Security review before launch
- We reply within one working day.
- IETF RFC 9110 (June 2022), section 15.5.4
- Google AIP-193 and AIP-211
- Microsoft Azure REST API Guidelines
- OpenAPI Specification 3.2.1
- IETF RFC 9745 (March 2025)
In brief
- What it is
- We build documented APIs (the connections that let software exchange data), connect third-party services, and write the middleware (the in-between code) that lets two separately built systems work together.
- Why it matters
- Every API must decide which records each caller (the app, partner or person sending a request) may reach, and what a refused caller is told. Leave that unwritten and parts of the API can answer differently, and a careless answer can reveal that a record exists.
- What you get
- A written API contract that answers those questions without anyone opening the code, an API built to it, and a security review of our build before launch.
What we do
Build the API, connect the systems, write the rules down.
Integrations and middleware
We connect your software to third-party services, and write the middleware that gets two separately built systems to agree on what counts as a customer. We scope each integration separately.
A security review before launch
Our security practice reviews our builds before launch. Checking a running API for which caller can reach which record is a separate service: API vulnerability assessment.
Related: checking each user's access inside a web app (web application development), building around the system that holds your records (enterprise software development), keeping each customer's data apart (SaaS development) and deciding whether to build or buy (custom software development).
The 403 or 404 decision
Decide what a refused caller is told.
RFC 9110, Microsoft and Google each give an API a way to keep a record's existence hidden.
When a caller asks for a record it may not see, the API can answer 403 (forbidden) or 404 (not found). A 403 can tell the caller that the record exists. RFC 9110 lets a 404 hide it. Google's AIPs (API Improvement Proposals) return 403 and hide it in the message instead.
Microsoft's Azure REST API Guidelines prefer 403, which customers find easier to debug. They switch to 404 when admitting the record exists could expose a customer's secrets.
Google's AIP-193 has services check permission before existence, so a caller without permission gets 403 whether or not the record exists. Google's AIP-211 says a 404 that turns into a 403 once a caller has enough permission is counter-intuitive and harder to troubleshoot.
Our reading: both hold up. The API contract is where one gets chosen, not the first piece of code written.
What the contract writes down about callers and records
- Refused callers. The status a caller gets for a record it may not see, 403 or 404, the same on every endpoint (each address the API answers at).
- Security on every operation. Each operation declares its own security, and any operation left open is open on purpose.
- Field-level rules. Which fields a caller may read or change, set by the caller's permissions and the record's attributes, including its state or status.
- Whose permissions count downstream. Whether a service further down the chain decides on the originating caller's permissions or on a service token (the system's own credential).
- A deprecation policy clients can find. The plan for retiring old versions, linked from the API itself.
The clauses behind these rules
- Security on every operation. In an OpenAPI Specification 3.2.1 description, an operation's security list overrides the top-level one, an empty array removes it, and {} marks anonymous access. We read those override rules as a reason to declare security on each operation, with any empty array or {} there on purpose. OpenAPI 3.2.1 defines no field for which caller may reach which record.
- Field-level rules. OWASP ASVS 5.0.0 (the Application Security Verification Standard) lists field-level read and write rules as v5.0.0-8.1.2, a Level 2 requirement.
- Whose permissions count downstream. OWASP ASVS 5.0.0 addresses this in v5.0.0-8.3.3, a Level 3 requirement.
- A deprecation policy clients can find. Clients find it through the deprecation link relation, which IETF RFC 9745 allows before or after the deprecation itself.
Where contracts slip
Three mistakes to avoid, each traced to the document behind it.
Validating before authorizing
Validating checks that a request is well formed; authorizing checks that the caller may make it. Google's AIP-211 is direct: “Services must check authorization before validating any request, to ensure both a secure API surface and a consistent user experience.” Validate first, and the error can tell a caller more than a 403.
Using OAuth flows a specification still lists
OAuth is the standard many APIs use to hand out access tokens. OpenAPI Specification 3.2.1 still lists the implicit and password flows (two ways to get a token) among those it supports, and says that is no endorsement. RFC 9700 (January 2025) says the password grant must not be used, and the implicit grant should not be, except under conditions it states.
Trusting a portal that contradicts itself
NIC's e-Invoice API Developer's Portal, Authentication v1.04, contradicts itself on token refresh: its overview allows forcing a new token in the last 10 minutes before expiry; the same page's FAQ says a new token comes only after expiry.
Deprecation and Sunset
Retiring an API version, in five steps.
Google's API rules and two IETF RFCs, in the order a team meets them. The ordering is ours.
Keep minor releases compatible
Google's AIP-180, a rule for Google's own APIs, says a new minor or patch release must not break existing client code.
Announce with a Deprecation header
IETF RFC 9745 (March 2025) defines a Deprecation response header, a line the API adds to its responses. Its value must be a date in a fixed format, a Structured Field Date, such as @1688169599.
Expect no change at deprecation
RFC 9745 is plain: “The act of deprecation does not change any behavior of the resource.” Client developers must still stop assuming it stays the same.
Set Sunset no earlier than Deprecation
RFC 9745 says the Sunset timestamp must not be earlier than the Deprecation timestamp, so nothing is scheduled to go before it is deprecated.
Read Sunset as a hint
RFC 8594 (May 2019), an Informational RFC, defines Sunset and tells clients to treat a Sunset timestamp as a hint, not a fixed cutoff.
India: ReBIT, ONDC, DigiLocker
Indian API specifications don't keep the record rule in one place.
We read three published specifications for two questions: who is calling (how a caller proves who it is) and which records that caller may reach. Two answer the second through consent; for ONDC, the documents read do not say.
| Specification, as its publisher prints it | Question | What the document prints |
|---|---|---|
| ReBIT Account Aggregator API 2.1.0 | Who is calling | API key headers and an x-jws-signature of the body |
| ReBIT Account Aggregator API 2.1.0 | Which records | The Account Aggregator (AA) validates requests against the signed consent |
| ONDC, Auth Header - signing and verification, 0.1 | Who is calling | Key looked up in the registry by ukId; 401 on failure |
| ONDC, Auth Header - signing and verification, 0.1 | Which records | Not established from the documents read |
| DigiLocker Requester API Specification, Version 1.12 | Who is calling | OAuth 2.0 with code_challenge required, S256 only |
| DigiLocker Requester API Specification, Version 1.12 | Which records | The consent screen, narrowed by req_doctype |
What this table is not. It records what each publisher prints about its own specification. It does not describe any SecWiz integration.
By our reading, either can be right, so the API contract has to say which. Section 15.5.4 of RFC 9110, which obsoletes RFC 7231, lets a server hide a forbidden resource behind a 404, and Microsoft's Azure and Graph guidelines use 404 where a 403 would disclose that the record exists. Google's AIP-193 and AIP-211 give 403 to a caller without permission, with a message saying the resource might not exist, and keep NOT_FOUND for permitted callers.
Yes. RFC 9396 (May 2023) lets an authorization request name a specific resource at the API, and leaves each field's allowable values to that API. RFC 9700 says tokens should be limited to particular resources and actions, and obliges every resource server to check each request's token against the action and resource requested. The API still decides which records a caller may be granted.
No. OAuth 2.1 is still an IETF Internet-Draft, not an RFC. As of September 2026 the IETF Datatracker lists draft-ietf-oauth-v2-1 as an active draft. The published framework remains RFC 6749 as updated by RFC 9700 (January 2025), so a contract that names its OAuth rules can cite those RFCs and treat the draft as a draft.
Through response headers. IETF RFC 9745 (March 2025) makes the Deprecation value a Structured Field Date and requires any Sunset timestamp to be no earlier than that date. Deprecation changes nothing about the resource, but client developers must stop assuming it will stay the same. RFC 8594 (May 2019), an Informational RFC, defines Sunset and tells clients to read it as a hint.
RFC 9457, which obsoletes RFC 7807, defines problem details for HTTP APIs. A status member in the body must match the status code actually sent, so software that ignores the format still sees the right code. The RFC also warns that error details can leak information that endangers the system or its users. Microsoft's Azure guidelines treat x-ms-error-code values as fixed parts of the contract.
Not in one place. In ReBIT's Account Aggregator API 2.1.0, the aggregator validates a request against the signed consent. DigiLocker's Requester API Specification, Version 1.12, narrows a consent screen with req_doctype and returns HTTP 403 for insufficient_scope. For ONDC's document on Auth Header signing and verification, version 0.1, an Initial draft, the documents read do not establish a record rule. This describes the documents, not a SecWiz integration.
Let's talk
Tell us what the API has to tell a caller.
List who calls the API and what a caller should learn when a record is not theirs. Project work is delivered remotely from India during business hours. We reply within one working day.