GovWire

API

Do not expand the acronym for technical users.

API endpoints

Use methodname endpoint for an API endpoint. Do not include the base path. Use {CAPS_WITH_UNDERSCORES_INSIDE_CURLY_BRACKETS} for placeholder parameters in endpoints.

For example:

GET /v1/payments/{PAYMENT_ID}/{REFUND_ID}

Replace:

• {PAYMENT_ID} with the ID of the payment youre checking
• {REFUND_ID} with the ID of the refund youre checking

API headers

There are lots of HTTP and API headers, so use code style and the exact name of API headers, to make it clear which heading you mean. For example:

• Authorisation header
• Content-type header - not Content header because there are several different content headers

Example:

You must include an Authorisation` header in your request.

API key

Do not expand the acronym for technical users. Use:

• create an API key - not generate
• revoke an API key

API parameters and fields

Use:

• parameter for API request items, not option
• field for API response items, not variable
• object, not dictionary or array - for example: If the status in the refund_summary object is available
• key
• value
• key-value pair

Parameters are required or optional. Do not use you do not need (which is ambiguous) or you can leave out.

API requests

Use API request not API call.

Tell users they can include a parameter in an API request, not that they can supply a parameter.

bold

Only use bold in text from interfaces.

breaking changes

Breaking changes are changes to one part of your software system that may cause other parts to fail. Do not use this term without explaining it - user research shows not all technologists immediately understand what it means.

choose

Use choose where theres a genuine choice (like choose what time you want your appointment) and select when youre indicating the appropriate response (like select your year of birth).

Cloud First policy

Capitalise Cloud First.

Cloud Security Principles

Upper case.

code samples

Format code samples or excerpts in a fixed width font. You usually do this by adding either:

• backticks (```) around code excerpts inside sentences
• 3 backticks (````````) above and below code blocks

code styling

Use code styling for the following, which is based on the code styling list in Googles style guide:

• classes, methods and functions
• terminal commands
• fields - names and values
• data types
• filenames, extensions, paths and folders
• HTML element names
• HTTP status codes
• HTTP methods - for example GET and PUT
• placeholder variables

conditions

Use:

• you must for a requirement
• you should for a recommendation
• you can for an option or possibility

Do not use:

• it may be possible to - use you can
• you may want to - use you can
• where possible you - use where you can

Do not use block capitals. Its an accessibility issue, and user research shows that it does not help users recognise and understand requirements.

credential issuer

Write credential issuer the first time you refer to a credential issuer. You can then use issuer throughout the content.

Do not abbreviate credential issuer to CI or CRI.

CSS

Do not expand the acronym.

custom

We use this to mean your own, for example in:

• add a custom paragraph
• add custom metadata

data type

Not datatype.

data

Use the following:

• get data
• store data
• access data
• share data - not exchange data, unless data is going both ways

Treat data as a singular noun, so use the data is accurate not the data are accurate.

