From dcf684571ecdda351a50094c93cb5e4de57c887a Mon Sep 17 00:00:00 2001 From: anjumabbas Date: Tue, 29 Oct 2024 14:15:10 +0000 Subject: [PATCH 1/2] API-7709 - Unify api-definition-schema.json and api-definition.md --- app/resources/api-definition-schema.json | 9 ++- docs/api-definition.md | 77 +++++++++++------------- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/app/resources/api-definition-schema.json b/app/resources/api-definition-schema.json index d473a89..ba2451a 100644 --- a/app/resources/api-definition-schema.json +++ b/app/resources/api-definition-schema.json @@ -182,7 +182,10 @@ }, "UrlValidationRule": { "description": "A URL Rule to validate a URL field.", - "type": "object" + "type": "object", + "properties": { + + } } } } @@ -198,7 +201,7 @@ "type": "object", "properties": { "read": { - "description": "Who going to have Read Access to the value of this Subscription Field", + "description": "Who has Read Access to the value of this Subscription Field", "type": "string", "enum": [ "anyone", @@ -207,7 +210,7 @@ ] }, "write": { - "description": "Who going to have Write Access to the value of this Subscription Field", + "description": "Who has Write Access to the value of this Subscription Field", "type": "string", "enum": [ "anyone", diff --git a/docs/api-definition.md b/docs/api-definition.md index 6a22345..044bf41 100644 --- a/docs/api-definition.md +++ b/docs/api-definition.md @@ -4,7 +4,7 @@ Generated from [JSON schema](app/resources/api-definition-schema.json) HMRC API definition. See [JSON definition] | Name | Type | Required | Values | Description | -| --- | --- |----------| --- | --- | +| --- | --- | --- | --- | --- | | `api` | _object_ | Required | [api](#api) | Details of the API | ### `api` Details of the API @@ -12,82 +12,77 @@ Details of the API | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | | `name` | _string_ | Required | ^[A-Z]{1}.*$ | The name for the API (title case i.e. Individual Benefits, not Individual benefits). | -| `versions` | _object[]_ | Required | [versions](#versions) | A list of the different versions of the API | +| `description` | _string_ | Required | | The description for the API | | `context` | _string_ | Required | ^[a-z]+[a-z/\-]{4,}$ | The unique context for the API. This should be consistent with the HMRC Domain Model. See [API Domain Model](https://confluence.tools.tax.service.gov.uk/display/ApiPlatform/HMRC%27s+API+Domain+Model) | | `isTestSupport` | _boolean_ | Optional | False (default) | Categorises the API as being a Test Support API | | `categories` | _string[]_ | Optional | EXAMPLE
AGENTS
BUSINESS_RATES
CHARITIES
CONSTRUCTION_INDUSTRY_SCHEME
CORPORATION_TAX
CUSTOMS
ESTATES
HELP_TO_SAVE
INCOME_TAX_MTD
LIFETIME_ISA
MARRIAGE_ALLOWANCE
NATIONAL_INSURANCE
PAYE
PENSIONS
PRIVATE_GOVERNMENT
RELIEF_AT_SOURCE
SELF_ASSESSMENT
STAMP_DUTY
TRUSTS
VAT
VAT_MTD
OTHER | The list of service groups the API will be categorised by. | -| `description` | _string_ | Required | | The description for the API | +| `versions` | _object[]_ | Required | [versions](#versions) | A list of the different versions of the API | ### `versions` Details of an API version | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | +| `endpoints` | _None_ | Optional | | DEPRECATED | +| `version` | _string_ | Required | ^[0-9\.P]+$ | The version number. Eg 1.0 | | `status` | _string_ | Required | PROTOTYPED
PUBLISHED
ALPHA
BETA
STABLE
DEPRECATED
RETIRED | The current lifecycle status. PROTOTYPED and PUBLISHED should not be used. See [Lifecycle] | -| `fieldDefinitions` | _object[]_ | Optional | [fielddefinitions](#fieldDefinitions) | A list of subscription fields for this API version. | -| `access` | _object_ | Optional | [access](#access) | Used to indicate whether this API version is public or private. If absent, the API defaults to public. See [Access] | | `endpointsEnabled` | _boolean_ | Optional | True (default) | Whether the endpoints are shown as available on the DevHub documentation page. This does not effect if the API can actually be used / called. This value MUST be false if the API versions status is ALPHA | -| `version` | _string_ | Required | ^[0-9\.P]+$ | The version number. Eg 1.0 | -| `endpoints` | _None_ | Optional | | DEPRECATED | +| `access` | _object_ | Optional | [access](#access) | Used to indicate whether this API version is public or private. If absent, the API defaults to public. See [Access] | +| `fieldDefinitions` | _object[]_ | Optional | [fielddefinitions](#fieldDefinitions) | A list of subscription fields for this API version. | ### `access` Used to indicate whether this API version is public or private. If absent, the API defaults to public. See [Access] | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `isTrial` | _boolean_ | Optional | | Whether this API version is a private trial | | `type` | _string_ | Required | PUBLIC
PRIVATE | Whether the API version is publicly available or only for private use. | - +| `whitelistedApplicationIds` | _string[]_ | Optional | | DEPRECATED. This is no longer used. Please contact SDST to add applications to the allowlist. | +| `isTrial` | _boolean_ | Optional | | Whether this API version is a private trial | ### `fieldDefinitions` Details a subscription field used by this API. If you would like to use subscription fields you should talk to the API Platform team first #team-api-platform-sup. | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `shortDescription` | _string_ | Optional | | A short description that is displayed on the API metadata page | -| `validation` | _object_ | Optional | [validation](#validation) | Rules to validate the value of the Field Definition | -| `hint` | _string_ | Optional | | Hint text to display to users to help them provide a correct value for this field. If left blank the description will be used instead | -| `type` | _string_ | Required | URL
SecureToken
STRING
PPNSField | The type of value expected for this field | | `name` | _string_ | Required | ^[a-zA-Z]*$ | The internal identifier for this field | | `description` | _string_ | Required | | The description that will be shown to users for this field | -| `access` | _object_ | Optional | [access](#fieldaccess) | Access control for the value of this Subscription Field | - - - -### `access` -Access control for the value of this Subscription Field. See [Access](#fieldaccess) +| `type` | _string_ | Required | URL
SecureToken
STRING
PPNSField | The type of value expected for this field | +| `hint` | _string_ | Optional | | Hint text to display to users to help them provide a correct value for this field | +| `shortDescription` | _string_ | Optional | | A short description that is displayed on the API metadata page | +| `validation` | _object_ | Optional | [validation](#validation) | Contains Rules to validate the value of the Field Definition. | +| `access` | _object_ | Optional | [access](#access) | Access control for the value of this Subscription Field | +### `validation` +Contains Rules to validate the value of the Field Definition. | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `devhub` | _object_ | Optional | [devhub](#devhub) | Read / Write Access control within Developer Hub for the Subscription Field. | - -### `devhub` -The Regular Expression to validate the field value. See [DevHub] +| `errorMessage` | _string_ | Optional | | The error message that will be shown to users if this field is invalid. | +| `rules` | _object[]_ | Optional | [rules](#rules) | An array of Validation Rules to validate the field's value. | +### `rules` +A Validation Rule to validate the field value. | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `read` | _string_ | Optional | anyone
adminOnly
noOne | The required Read Access level for the Subscription Field. This defaults to anyone Access level | -| `write` | _string_ | Optional | anyone
adminOnly
noOne | The required Write Access level for the Subscription Field. This defaults to anyone Access level | - -### `validation` -Contains Rules to validate the value of the Field Definition. See [Validation] +| `RegexValidationRule` | _object_ | Optional | [regexvalidationrule](#RegexValidationRule) | A Regex Rule to validate the field value. | +| `UrlValidationRule` | _object_ | Optional | [urlvalidationrule](#UrlValidationRule) | A URL Rule to validate a URL field. | +### `RegexValidationRule` +A Regex Rule to validate the field value. | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `errorMessage` | _string_ | Required | | The error message that will be shown to users if this field is invalid. | -| `rules` | _object[]_ | Required | [rules](#rules) | An array of Validation Rules to validate the field's value. | - -### `rules` -Details of a Validation Rule. This currently only supports Regular Expression Rules. See [Rules] +| `regex` | _string_ | Optional | | Regex to validate the field value. | +### `UrlValidationRule` +A URL Rule to validate a URL field. | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `RegexValidationRule` | _object_ | Optional | [RegexValidationRule](#RegexValidationRule) | A Regular Expression Rule | -| `UrlValidationRule` | _object_ | Optional | [UrlValidationRule](#UrlValidationRule) | A URL Validation Rule | - -### `RegexValidationRule` -The Regular Expression to validate the field value. See [RegexValidationRule] +### `access` +Access control for the value of this Subscription Field | Name | Type | Required | Values | Description | | --- | --- | --- | --- | --- | -| `regex` | _string_ | Required | | A Regular Expression | +| `devhub` | _object_ | Optional | [devhub](#devhub) | Access control within Developer Hub for the value of this Subscription Field | +### `devhub` +Access control within Developer Hub for the value of this Subscription Field -### `UrlValidationRule` -This is an empty object to specify that URL Validation applies to the field's value. See [UrlValidationRule] +| Name | Type | Required | Values | Description | +| --- | --- | --- | --- | --- | +| `read` | _string_ | Optional | anyone
adminOnly
noOne | Who has Read Access to the value of this Subscription Field | +| `write` | _string_ | Optional | anyone
adminOnly
noOne | Who has Write Access to the value of this Subscription Field | From 16442866c907b0caa9b8ea7097a0f04bf68f7132 Mon Sep 17 00:00:00 2001 From: anjumabbas Date: Tue, 29 Oct 2024 14:32:15 +0000 Subject: [PATCH 2/2] API-7937 - Add generation of api-definition.md to run_all_tests script --- run_all_tests.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/run_all_tests.sh b/run_all_tests.sh index 3fadcac..10d52e8 100755 --- a/run_all_tests.sh +++ b/run_all_tests.sh @@ -2,3 +2,4 @@ export SBT_OPTS="-XX:MaxMetaspaceSize=1G" sbt pre-commit +./generate-api-definition-docs.py app/resources/api-definition-schema.json > docs/api-definition.md