Introduction

Purpose

These standards:

• Specify the requirements for designing and building RESTful APIs.

• Provide guidance for aligning with our API Strategy & Roadmap.

They are intended for API producers but may also assist teams integrating APIs into client applications.

Scope

In-scope

These standards apply to RESTful APIs designed and built for:

• Internal use within the organisation.

• External use by clients, partners, or third parties.

A good practice checklist is also included to assist teams in achieving compliance.

Out-of-scope

These standards do not apply to:

• Non-RESTful APIs, including GraphQL, gRPC, and event-driven APIs (e.g. Azure Functions).

• APIs designed primarily to handle large binary data (e.g. image or file delivery).

• Topics outside API design and implementation, such as Domain-driven design or microservices architecture.

• Infrastructure, networking, or Web Application Firewalls (WAF).

• API publishing pipelines (e.g. via Apigee).

• Telemetry, monitoring, or general software development practices.

References

1. The API Strategy and Roadmap
2. Software development handbook
3. Testing for lost updates
4. How to write a Test Summary Report
5. SDS-TEM-5 - Test Summary Report template
6. Using Source Control
7. How to Organise Your Software Solution
8. General Coding Standards
9. IG-TEM-1 - Data Protection Impact Assessment Form Template
10. DHCW-POL-5 - Service Level Target Policy

Conventions

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

The need for guidance

Conforming to these standards helps you build APIs that are consistent, easy to use, safe and secure.