swagger: '2.0'
info:
  description: >-
    This API makes market commentary text (Investment
    Environment and Market Outlook) available to external clients.
  version: v1.0.2
  title: Commentary API
  contact:
    email: manmeet.singh@fil.com
host: api.fil.com
basePath: /inst-marketcommentary-v1
tags:
  - name: Commentary
    description: Market Commentary.
schemes:
  - https
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.fil.com/identity/v1/tokens?grant_type=client_credentials'
    scopes:
      read: Grants read access.
paths:
  '/outlooks/{year}/{quarter}':
    get:
      tags:
        - Commentary
      summary: Market Outlooks Commentary
      description: >-
        This operation will return the Market Commentary for all our Investment Environments. Please supply in the URL the year and quarter for which the market commentary is required.
      security:
        - OAuth2: []
      operationId: outlooks
      consumes:
        - application/json
        - application/xml
      produces:
        - application/json
      parameters:
        - name: year
          in: path
          description: |-
            Please supply the year for which commentary is required, it should be in the format YYYY e.g. 2017.
          required: true
          type: string
          default: 2017
        - name: quarter
          in: path
          description: |-
            Please supply the quarter for which commentary is required, it should be one of the following Q1, Q2, Q3, Q4.
          required: true
          type: string
          default: Q1
      responses:
        '200':
          description: Market commentary for all market outlooks.
          schema:
            $ref: '#/definitions/MarketOutlookResponse'
          examples:
            '200':
              outlooks:
                - assetClass: Global Equities
                  text: The economic backdrop in developed ...
                - assetClass: UK Equities
                  text: The UK economy has seen a robust ...
              links:
                - href: >-
                    https://cat.fidelity.co.uk/gateway/inst/marketcommentary/v1/environments/2015/q1
                  method: GET
                  rel: self
        '400':
          description: >-
            Bad request. Refer to the moreinfo section for details.  Please check that you've entered the correct parameters.
          examples:
            Invalid Period end date (Future Date):
              errorCode: PMC002
              developerMessages:
                - The Period end date can't be future date.
              userMessage: The Period end date can't be future date
              trackingId: 4c5c70b1-9c6d-4f57-837c-fd558a99bb38
        '401':
          description: Unable to authorize the credentials that were supplied.
        '500':
          description: >-
            There was an internal issue calling the service. This is likely to be a permanent error. Please contact FIL for support.
  '/environments/{year}/{quarter}':
    get:
      tags:
        - Commentary
      summary: Investment Environments commentary
      description: >-
        This operation will give you the Market Commentary for all the
        Investment Environments. Enter the year and quarter for which the market commentary is required.
      security:
        - OAuth2: []
      operationId: environments
      consumes:
        - application/json
        - application/xml
      produces:
        - application/json
      parameters:
        - name: year
          in: path
          description: |-
            Please supply the year for which commentary is required, it should be in the format YYYY e.g. 2017.
          required: true
          type: string
        - name: quarter
          in: path
          description: |-
            Please supply the quarter for which commentary is required, it should be one of the following Q1, Q2, Q3, Q4.
          required: true
          type: string
      responses:
        '200':
          description: Market commentary for all market outlooks.
          schema:
            $ref: '#/definitions/InvestmentEnvironmentResponse'
          examples:
            '200':
              environments:
                - marketName: Australian Equities
                  themes:
                    - name: Global volatility impacted Australian...
                      text: Australian equities declined over the ...
                      serialNumber: 1
                    - name: Service sector growth picking up
                      text: Australian equities declined over the ...
                      serialNumber: 2
                    - name: Resource sector earnings downgraded
                      text: Australian equities declined over the ...
                      serialNumber: 3
                - marketName: Bonds
                  themes:
                    - name: A mixed quarter for fixed income assets...
                      text: Australian equities declined over the ...
                      serialNumber: 1
                    - name: Global economic growth is slowing
                      text: Australian equities declined over the ...
                      serialNumber: 2
                    - name: Corporate credit warrants careful selection
                      text: Australian equities declined over the ...
                      serialNumber: 3
              links:
                - href: >-
                    https://cat.fidelity.co.uk/gateway/inst/marketcommentary/v1/environments/2015/q1
                  method: GET
                  rel: self
        '400':
          description: >-
            Bad request. Refer to the moreinfo section for details.  Please check that you've entered the correct parameters.
          examples:
            Invalid Period end date (Future Date):
              errorCode: PMC002
              developerMessages:
                - The Period end date can't be a future date.
              userMessage: The Period end date can't be future date
              trackingId: 4c5c70b1-9c6d-4f57-837c-fd558a99bb38
        '401':
          description: Unable to authorize the credentials that were supplied.
        '500':
          description: >-
            There was an internal issue calling the service. This is likely to be a permanent error. Please contact FIL for support.
definitions:
  InvestmentEnvironmentResponse:
    type: object
    properties:
      environments:
        type: array
        items:
          type: object
          properties:
            marketName:
              type: string
              description: The market name.
            themes:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: The theme name.
                  text:
                    type: string
                    description: The commentary text.
                  serialNumber:
                    type: integer
                    description: The commentary position.
      links:
        type: array
        description: >-
          The array of hypermedia links to access the resources related to the current resource.
        items:
          type: object
          properties:
            href:
              type: string
              description: The href of the resorce for HATEOS.
            method:
              type: string
              description: The HTTP method to get the resource.
            rel:
              type: string
              description: 'The relationship with the currect resource, self, parent, etc.'
  MarketOutlookResponse:
    type: object
    properties:
      outlooks:
        type: array
        items:
          type: object
          properties:
            assetClass:
              type: string
              description: The Asset class of the Market Outlook.
            text:
              type: string
              description: The commentary text for the asset class.
      links:
        type: array
        description: >-
          The array of hypermedia links to access the resources related to the current resource.
        items:
          type: object
          properties:
            href:
              type: string
              description: The href of the resorce for HATEOS.
            method:
              type: string
              description: The HTTP method to get the resource
            rel:
              type: string
              description: 'The relationship with the currect resource, self, parent, etc.'
  ApiResponse:
    type: object
    properties:
      errorCode:
        type: string
      developerMessages:
        type: array
        items:
          type: string
      userMessage:
        type: string
        description: The description of the error.
      trackingId:
        type: string
        description: The tracking Id to debug the issue.
