Public-sector integrations force you to design for slow cycles, unreliable networks, and clients you cannot control. That pressure produces better engineering habits.
The Government API Problem
When you build an API for a startup, your consumer is a team of engineers who share a Slack workspace with you. When you build an API for a government system, your consumers might be a 1995 mainframe, a third-party vendor who hasn't updated their SDK in four years, and a junior developer in a ministry IT department who only has access to Postman.
These constraints change everything.
Principle 1: Version Aggressively, Deprecate Slowly
Private sector APIs can deprecate old versions in 6 months. Government procurement and IT approval cycles often take 12–18 months. We never deprecate a government API version in under two years, and we maintain at least three major versions simultaneously.
Our URL pattern: /api/v3/procurement/requests. We never use header-based versioning for government clients — not all clients can set custom headers reliably.
Principle 2: Idempotency is Non-Negotiable
Network conditions in many Nigerian states are unreliable. A client may receive a timeout error and retry a request that actually succeeded. Without idempotency keys, this creates duplicate records — a catastrophe in financial systems.
Every mutating endpoint accepts an Idempotency-Key header. We store keys with a 24-hour TTL and return the cached response for duplicate requests within that window.
Principle 3: Verbose Error Responses
Generic error messages like {"error": "Bad Request"} are useless to a developer who can't reach you on Slack. We use RFC 7807 Problem Details:
{
"type": "https://api.bit4orge.com/errors/validation",
"title": "Validation Failed",
"status": 400,
"detail": "The 'procurement_value' field must be a positive integer in kobo.",
"instance": "/api/v3/procurement/requests/REQ-2025-00441",
"errors": [
{
"field": "procurement_value",
"message": "Value -500 is not a positive integer",
"code": "INVALID_AMOUNT"
}
]
}
Principle 4: Machine-Readable Documentation
We generate OpenAPI 3.0 specs from code annotations and serve them at /api/docs. Every endpoint has example requests and responses. Every error code has a description. Integration partners can import the spec directly into Postman or Insomnia.
Principle 5: Plan for Offline Clients
Not every integration partner has always-on connectivity. We provide a bulk sync endpoint that accepts a since timestamp and returns all changes since that point. This lets offline clients catch up after connectivity is restored without re-fetching entire datasets.
Conclusion
Government API design is ultimately an exercise in empathy — for developers working under constraints you've never experienced, on timelines you can't control, with tools that may be a decade old. Design accordingly.
