openapi: "3.0.2"
# This is your document metadata.
info:
  title: Content lock
  description: |-
    This API product retrieves the level of content lock for a given account from 3 security levels.


  version: '0.14' 
# Servers where this API is hosted    
servers:
  - url: https://api.ee.co.uk
    description: Production
  - url: https://api-sandbox.ee.co.uk
    description: Sandbox
# Describe your paths here
paths:
  /v1/mobile-subscriptions/{identifier}/adult-content-lock:
    get:
      summary: Get content lock setting
      operationId: adultContentLock
      description: |-
        
        <p>This API returns the content lock setting which is applied to a given EE Mobile account.</p>
        <p> <b>Intermediate (Moderate)</b> </br>
            This is the default setting for new and existing customers with content lock enabled. This gives access to social networking sites but not to 18-rated content in accordance with BBFC (British Board of Film Classification) guidelines or to pornography sites. </br>
            <b>Off</b> </br>
            This gives full access to the internet with no filter including to 18-rated content. </br>
            <b>On (Strict)</b> </br>
            This is the safe setting for children under 12. It filters all 18-rated content but also content the BBFC rates higher than 'PG' as well as other content not suitable for younger children including chat, dating and unmoderated social networking sites.</p>
            <p>By default this API supports the Anonymised Mobile Subscriber Reference (AMSR) identifier in lieu of the subscriber's mobile phone number (MSISDN). The AMSR is obtained from the Network Identity API. Please contact us if you require to use MSISDN rather than AMSR.</p>
         
        <details>
        <summary><b>Sandbox responses</b></summary>

        <p>The sandbox supports a number of success and failure scenarios which can be simulated by changing the last 6 characters of the X-EE-EL-Tracking-Header as defined in the tables below.</p>
       
        <details>
        <summary><b>Success scenarios</b></summary> 

        | X-EE-EL-Tracking-Header (last 6 characters) | Sandbox response invoked | Description |
        | ----------- | ------------------- | ------------------ |      
        | default | 200 | Simulates <i>lockSetting</i> Off. |
        | PASS01 | 200 | Simulates <i>lockSetting</i> Intermediate. |
        | PASS02 | 200 | Simulates <i>lockSetting</i> On. |

        </details>

        <details>
        <summary><b>Error scenarios</b></summary>    

        | X-EE-EL-Tracking-Header (last 6 characters) | Sandbox response invoked | Description | 
        | ----------- | ------------------- | -------- |
        | E02001 | 400, 20 | Invalid URL parameter value: <i>amsr</i>. |  
        | E06001 | 404, 60 | Resource not found. |   
        | E00101 | 500, 01 | Internal error. |
        | E00501 | 503, 05 | The service is temporarily unavailable. |

        </details>
        </details>

      x-codeSamples:
        - lang: 'Shell'
          label: cURL
          source: |   
            curl -XGET 
            -H "X-EE-EL-Tracking-Header: 96bb97fa-b941-46bb-8c4e-86c616c28a13"
            -H "Authorization: Bearer SZrYQsmi9tvGj1XwmKr5lXD4dpXY" 
            https://api-sandbox.ee.co.uk/v1/mobile-subscriptions/447700900000/adult-content-lock           
            
      security:
        - OAuth2: []

      # parameter section
      parameters:
        - name: X-EE-EL-Tracking-Header
          in: header
          example: 96bb97fa-b941-46bb-8c4e-86c616c28a13
          description: A unique reference used to track the transaction end to end. The recommended format is UUID (a 36-character alphanumeric string "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX").
          required: true
          schema: 
            type: string
            $ref: '#/components/schemas/trackingHeader'

        - name: Authorization
          in: header
          example: Bearer <token>
          description: "This contains the access token obtained from a call to the OAuth API. </br> The access token is prefixed with the word 'Bearer ' to form the authorisation string."
          required: true
          schema: 
            type: string

        - name: identifier
          in: path
          example: gjPab2w1z2_Zg-ZJIpyQ-g.. or 447700900000
          description: Either an Anonymised Mobile Subscription Reference or UK mobile phone number (12 digits in International format).
          required: true
          schema: 
            type: string

      # Expected responses for this operation:    
      responses:
        # Response code       
        '200':
          description: |
            OK
       
          # Response body content.           
          content:        
            # JSON response with a schema referenced from the
            # components object.           
           application/json:
            schema:
              $ref: '#/components/schemas/lockSetting'
            example: {"lockSetting": "off"}


        '400':    # status code
           description: |
            Bad Request

            | Code | Message | Description |
            | ---- | ------- | ----------- |
            | 20 | Invalid URL parameter value | One or more parameters in the URL are not valid. | 
            | 25 | Missing header: \<parameter\> | The indicated parameter is missing from the request header. |
           content:        
            application/json:
             schema:
                $ref: '#/components/schemas/FailureResponse'
             example: {"code": "20", "message": "Invalid URL parameter value"}   
           headers:
            X-EE-Exception:
              schema:
                type: string
              description: Header carrying the message of the exception.
            X-EE-Exception-Code:
              schema:
                type: string
              description: Header carrying the code of the exception.
            X-EE-Exception-System:
              schema:
                type: string
              description: Header carrying the system from which the exception has originated.
            Content-Type:
              schema:
                type: string
              description: This indicates the format of the error response.

        '403':    # status code
           description: |
            Forbidden

            | Code | Message | Description |
            | ---- | ------- | ----------- |
            | 51 | Forbidden requester | The client application has been blocked from calling this resource. |
           content:        
            application/json:
             schema:
                $ref: '#/components/schemas/FailureResponse'
             example: {"code": "51", "message": "Forbidden requester"}   
           headers:
            X-EE-Exception:
              schema:
                type: string
              description: Header carrying the message of the exception.
            X-EE-Exception-Code:
              schema:
                type: string
              description: Header carrying the code of the exception.
            X-EE-Exception-System:
              schema:
                type: string
              description: Header carrying the system from which the exception has originated.
            Content-Type:
              schema:
                type: string
              description: This indicates the format of the error response.

        '404':    # status code
           description: |
            Not Found

            | Code | Message | Description |
            | ---- | ------- | ----------- |
            | 60 | Resource not found | The requested URI or resource does not exist. |
           content:        
            application/json:
             schema:
                $ref: '#/components/schemas/FailureResponse'
             example: {"code": "60", "message": "Resource not found"}   
           headers:
            X-EE-Exception:
              schema:
                type: string
              description: Header carrying the message of the exception.
            X-EE-Exception-Code:
              schema:
                type: string
              description: Header carrying the code of the exception.
            X-EE-Exception-System:
              schema:
                type: string
              description: Header carrying the system from which the exception has originated.
            Content-Type:
              schema:
                type: string
              description: This indicates the format of the error response.

        '500':    # status code
           description: |
            Internal Server Error

            | Code | Message | Description |
            | ---- | ------- | ----------- |
            | 01 | Internal Error | BT error code. |
           content:        
            application/json:
             schema:
                $ref: '#/components/schemas/FailureResponse'
             example: {"code": "01", "message": "Internal Error"}   
           headers:
            X-EE-Exception:
              schema:
                type: string
              description: Header carrying the message of the exception.
            X-EE-Exception-Code:
              schema:
                type: string
              description: Header carrying the code of the exception.
            X-EE-Exception-System:
              schema:
                type: string
              description: Header carrying the system from which the exception has originated.         
            Content-Type:
              schema:
                type: string
              description: This indicates the format of the error response.

        '503':    # status code
           description: |
            Service Unavailable

            | Code | Message | Description |
            | ---- | ------- | ----------- |
            | 05 | The service is temporarily unavailable | Please try again later. |
           content:        
            application/json:
             schema:
                $ref: '#/components/schemas/FailureResponse'
             example: {"code": "05", "message": "The service is temporarily unavailable"}   
           headers:
            X-EE-Exception:
              schema:
                type: string
              description: Header carrying the message of the exception.
            X-EE-Exception-Code:
              schema:
                type: string
              description: Header carrying the code of the exception.
            X-EE-Exception-System:
              schema:
                type: string
              description: Header carrying the system from which the exception has originated.
            Content-Type:
              schema:
                type: string
              description: This indicates the format of the error response.

components:
  # Schemas is a map of names to Schema objects
  securitySchemes:
    OAuth2:
      type: oauth2
      description: This API requires [OAuth API](/node/360) validation. 
      flows:
        clientCredentials:
          tokenUrl: https://api.platform.bt.com/oauth/accesstoken?grant_type=client_credentials
          scopes: {}
            
  schemas:
    trackingHeader:
      type: string
      description: A unique client reference used to track the transaction end to end; it is recommended that the developer and app names are included for ease of debugging. The recommended format is UUID (a 36-character alphanumeric string "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX").
      pattern: ^[\w.~:@-]{1,255}$      

    lockSetting:
      properties:
       lockSetting:
        type: string
        description: "On - adult content lock is on and therefore no adult content is allowed. </br> Off - no lock setting and therefore no restrictions. </br> Intermediate - allowed access to content defined as intermediate."
        enum:
          - On
          - Off
          - Intermediate
     
    FailureResponse:
       type: object
       required:
        - code
        - message
       properties:
        code:
          type: string
          description: Represents the error code. 
        message:
          type: string
          description: Represents the error message.