Skip to content

Commit

Permalink
Merge pull request #20 from hmrc/SAR-70
Browse files Browse the repository at this point in the history 
SAR-70: Added the RAML documentation and JSON schemas et al.
  • Loading branch information
@MJCallahanPage
MJCallahanPage authored Dec 1, 2016
2 parents e2e9816 + 596870f commit 34049d8
Show file tree
Hide file tree
Showing 6 changed files with 240 additions and 116 deletions.
111 changes: 58 additions & 53 deletions resources/public/api/conf/1.0/application.raml
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
#%RAML 1.0
---
title: Hello World
title: Making Tax Digital Income Tax Subscription
version: 1.0

protocols: [ HTTPS ]
baseUri: https://api.service.hmrc.gov.uk/

Expand All @@ -14,70 +13,76 @@ documentation:
- title: Errors
content: !include http://api-documentation-raml-frontend.service/api-documentation/assets/common/docs/errors.md

mediaType: application/hal+json
mediaType: [ application/json, application/hal+json ]

uses:
sec: http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/securitySchemes.raml
headers: http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/headers.raml

annotationTypes:
config: object
group:
type: object
properties:
name: string
description: string
scope:
annotations: http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/annotations.raml
types: http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/types.raml

/income-tax:
/hello-world:
get:
displayName: Say hello world
/subscription:
post:
displayName: Post MTD Income Tax subscription
description: |
A simple example for integrating with an unrestricted service.
Allows a user to subscribe to the Making Tax Digital Income Tax service.
Any request to this endpoint initiates a 'Hello World' response.
It's a user-restricted endpoint which requires an OAuth 2.0 `access_token`.
is: [headers.acceptHeader]
(annotations.scope): "write:income-tax"
securedBy: [ sec.oauth_2_0: { scopes: [ "write:income-tax" ] } ]
body:
application/json:
schema: !include schemas/create-subscription-request.json
examples:
example-1:
value: !include examples/create-subscription-request-1.json
responses:
200:
201:
400:
body:
application/json:
example: |
{
"message" : "Hello World"
}
/hello-user:
get:
displayName: Say hello user
description: |
A simple example for integrating with a user-restricted service, using a OAuth 2.0 `access_token`.
Any authorised request to this endpoint initiates a 'Hello User' response.
is: [headers.acceptHeader]
(scope): "hello"
securedBy: [ sec.oauth_2_0: { scopes: [ "hello" ] } ]
responses:
200:
type: types.errorResponse
examples:
badRequest:
scenario: Bad Request
code: BAD_REQUEST
badRequest2:
scenario: Invalid request payload
code: BAD_REQUEST
401:
body:
application/json:
example: |
{
"message": "Hello User"
}
/hello-application:
get:
displayName: Say hello application
description: |
A simple example for integrating with an application-restricted service, using your `server_token`.
Any authorised request to this endpoint initiates a 'Hello Application' response.
is: [headers.acceptHeader]
securedBy: [ sec.x-application ]
responses:
200:
type: types.errorResponse
examples:
unauthorized:
scenario: Unauthorized
code: UNAUTHORIZED
404:
body:
application/json:
type: types.errorResponse
examples:
notFound:
scenario: Resource Not Found
code: NOT_FOUND
406:
body:
application/json:
type: types.errorResponse
examples:
acceptHeader:
scenario: Accept Header Invalid
code: ACCEPT_HEADER_INVALID
contentType:
scenario: Content-Type Header Invalid
code: CONTENT_TYPE_HEADER_INVALID
500:
body:
application/json:
example: |
{
"message": "Hello Application"
}
type: types.errorResponse
examples:
internalError:
scenario: Internal Server Error
code: INTERNAL_SERVER_ERROR
4 changes: 4 additions & 0 deletions resources/public/api/conf/1.0/examples/create-subscription-request-1.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"email": "[email protected]",
"acceptsTermsAndConditions": true
}
16 changes: 16 additions & 0 deletions resources/public/api/conf/1.0/schemas/create-subscription-request.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Create MTD IT Subscription",
"type": "object",
"properties": {
"email": {
"description": "The email address used to contact the user about their MTD IT service subscription",
"type": "string"
},
"acceptsTermsAndConditions": {
"description": "A field to indicate whether the user agrees to the Terms & Conditions of the MTD IT service",
"type": "boolean"
}
},
"required": ["email","acceptsTermsAndConditions"]
}
4 changes: 2 additions & 2 deletions resources/public/api/definition.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
}
],
"api": {
"name": "Income Tax",
"name": "Making Tax Digital Income Tax Subscription",
"description": "Income Tax services, such as subscription to Making Tax Digital Income Tax.",
"context": "income-tax",
"versions": [
Expand All @@ -17,7 +17,7 @@
"endpoints": [
{
"uriPattern": "/subscription",
"endpointName": "Subscribe to MTD Income Tax",
"endpointName": "Create Subscription",
"method": "POST",
"authType": "USER",
"throttlingTier": "UNLIMITED",
Expand Down
160 changes: 160 additions & 0 deletions resources/public/api/documentation/1.0/Create-Subscription.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
<endpoint>
<name>Create Subscription</name>
<description>This endpoint allows users to subscribe to the Making Tax Digital for Business - Income Tax service.</description>

<section id="resource">
<title>Resource</title>
<resource>POST /income-tax/subscription</resource>
</section>

<section id="authorisation">
<title>Authorisation</title>
<authorisation>
<type>USER</type>
<scope>write:income-tax</scope>
</authorisation>
</section>

<section id="content-types">
<title>Accepted Media Types</title>
<list>
<item>
<code>application/vnd.hmrc.1.0+json</code>
</item>
</list>
</section>

<section id="sample-request">
<title>Request</title>
<json>
<![CDATA[
{
"email": "[email protected]",
"acceptsTermsAndConditions": true
}
]]>
</json>
</section>

<section id="response">
<title>Response</title>
<httpStatus>201 (CREATED)</httpStatus>
</section>

<section id="error-responses">
<title>Error Scenarios</title>
<table>
<headings>
<cell>Error Scenario</cell>
<cell>HTTP Status</cell>
<cell>Error Code</cell>
<cell>message</cell>
</headings>
<rows>
<row>
<cell>
<code>Bad Request</code>
</cell>
<cell>
<code>400 (Bad Request)</code>
</cell>
<cell>
<code>BAD_REQUEST</code>
</cell>
<cell>
<code>Bad Request</code>
</cell>
</row>

<row>
<cell>
<code>Invalid request payload</code>
</cell>
<cell>
<code>400 (Bad Request)</code>
</cell>
<cell>
<code>BAD_REQUEST</code>
</cell>
<cell>
<code>Invalid payload</code>
</cell>
</row>

<row>
<cell>
<code>Unauthorized</code>
</cell>
<cell>
<code>401 (Unauthorized)</code>
</cell>
<cell>
<code>UNAUTHORIZED</code>
</cell>
<cell>
<code>Bearer token is missing or not authorized</code>
</cell>
</row>
<row>
<cell>
<code>Resource Not Found</code>
</cell>
<cell>
<code>404 (Not Found)</code>
</cell>
<cell>
<code>NOT_FOUND</code>
</cell>
<cell>
<code>Resource was not found</code>
</cell>
</row>

<row>
<cell>
<code>Accept header invalid</code>
</cell>
<cell>
<code>406 (Not Acceptable)</code>
</cell>
<cell>
<code>ACCEPT_HEADER_INVALID</code>
</cell>
<cell>
<code>The accept header is missing or invalid</code>
</cell>
</row>

<row>
<cell>
<code>Content-Type header invalid</code>
</cell>
<cell>
<code>406 (Not Acceptable)</code>
</cell>
<cell>
<code>CONTENT_TYPE_HEADER_INVALID</code>
</cell>
<cell>
<code>The content type header is missing or invalid</code>
</cell>
</row>

<row>
<cell>
<code>Internal Server Error</code>
</cell>
<cell>
<code>500 (Internal Server Error)</code>
</cell>
<cell>
<code>INTERNAL_SERVER_ERROR</code>
</cell>
<cell>
<code>Internal server error</code>
</cell>
</row>
</rows>
</table>
</section>
</endpoint>
Loading

0 comments on commit 34049d8

Please sign in to comment.