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.
