openapi: 3.0.0
info:
  version: 1.0-beta
  title: Sample Marketplace Partner Setup API
  description: |
    # Summary

    This document describes the endpoints used to manage vendor configurations
    within the Sample Marketplace.


    # Disclaimer

    Subject to the execution of a Non-Disclosure Agreement with FocusVision Worldwide, Inc (“Forsta”), Forsta hereby grants you a limited, revocable, non-exclusive, non-transferable,
    non-sublicensable license during the term of the Agreement to:
    (a) use the API solely for your internal business purposes in developing Your Applications that will communicate and interoperate with the Forsta Offering; and
    (b) display certain Forsta Marks in compliance with usage guidelines that we may specify from time to time solely in connection with the use of the API and the Applications
    and not in connection with the advertising, promotion, distribution, or sale of any other products or services. You acknowledge that there are no implied licenses granted under this Agreement.
    We reserve all rights that are not expressly granted. You may not use the API or any Forsta Mark for any other purpose without our prior written consent.
    You must obtain an API Key through the registration process available to use and access the API. You may not share your API Key with any third party, must keep your API Key and all log-in information secure,
    and must use the API Key as your sole means of accessing the API. Your API Key may be revoked at any time by us.


    # Versioning

    The API version is occasionally changed as new functionality is added, so API calls are versioned to ensure that clients don't break.

    The current API version is 1.0-beta. To use this version specifically, use the endpoints that are prefixed with `/v1.0`

    The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer API versions.

    This documentation is for version 1.0 of the API. The table below will be used to find documentation for previous versions of the API:

    API version | Changes
    ------------|---------
    [1.0-beta](#) | [API changes](#)

    # Integration Process

    ## Obtaining Access

    To obtain authentication credentials, you must first contact your Forsta
    representative and request credentials. After this, your app will be added to the
    system in a deactivated state. Using the provided credentials, you may then
    use these endpoints to customize your app's setup within the system.

    ## Customizing APISpec

    The <a href="#tag/APISpec">APISpec</a> endpoints allow you to customize your app's
    authentication and resource URI information. This is used by the sample marketplace
    to interact with your app, and the URIs specified must conform to the API contract.

    ## Customizing Sample Source

    The <a href="#/tag/Sample-Source">Sample Source</a> endpoints allow you to customize
    your app's required information for entry and exit links. This is used by the surveying
    platform to configure samples matching your requirements.

    ### Secure Exit Links

    A secure `token` query parameter is automatically added to all exit links from the marketplace.
    This query parameter will contain a JSON Web Token that is signed using the client secret
    provided in the APISpec section of the partner configuration. This token may be used to
    verify the authenticity of completes. Below is an example of the JWT payload:

    ```
    {
      "iss": "fv-smp",
      "iat": 1583862164,
      "survey_path": "selfserve/53a/200204",
      "domain": "https://release.decipherinc.com"
    }
    ```

    ## Test Runner

    To validate the implementation of the API Contract, we will use a test runner.
    This test runner has been made publicly available [here](static/media/test-runner.zip). 
    We will use this test runner to ensure that each of the endpoints work as expected.

    All requests that come from the test runner include the header <b>"X-FV-TEST"</b> with a value of "true" to enable
    the ability to differentiate fake requests from real requests.
    For more information on how to run the test runner, refer to the readme within the zipped test runner.

    ## Approval

    Once your configuration is adequately customized, you may then request a manual review
    from your Forsta representative. Our team will then work to ensure the setup is
    valid and your API matches the requirements specified in the API contract. Once this is
    finished, your app's status will become active, and will then be available for users
    within the Sample Marketplace.

    ## Future Changes

    Future changes will again require another manual review and approval process. Details TBD.
servers:
  - url: https://eks.us-west-2.fvdev.net/smp-partner-service
    description: Staging Environment
  - url: https://us-west-2-eks.aws.focusvision.com/smp-partner-service
    description: Production Environment
paths:
  /oauth2/token:
    post:
      summary: Client Credentials Access Token
      tags:
        - OAuth2
      description: |-
        This is used to gain an access token to use for the rest of the APIs following the <a href="https://tools.ietf.org/html/rfc6749#section-4.4">Client Credentials Grant</a> flow of the OAuth2 spec. Authorization used for this endpoint should be of the form `Basic Base64Encode(client_id:client_secret)`. You must obtain both `client_id` and `client_secret` from Forsta before gaining access to this API.

        Staging link: https://eks.us-west-2.fvdev.net/smp-partner-service/v1.0/oauth2/token


        Production link: https://us-west-2-eks.aws.focusvision.com/smp-partner-service/v1.0/oauth2/token
      security:
        - BasicAuth: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1.0/app:
    get:
      summary: Get your app's information
      tags:
        - App
      description: This returns the current information about your app that is in our system. These properties are configured and managed by Forsta as part of the initial signup process.
      security:
        - OAuth2: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAppResponse'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /v1.0/app/apispec:
    get:
      summary: Get your app's current API Configuration
      tags:
        - APISpec
      description: This returns the current configuration of your app's API used in the marketplace. The API must conform to the specifications laid out in the API contract, including implementing an OAuth2 client credentials flow and endpoints for the required resources.
      security:
        - OAuth2: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    patch:
      summary: Merge update a vendor's API Configuration
      tags:
        - APISpec
      description: This performs a <a href="https://tools.ietf.org/html/rfc7396">JSON Merge Patch</a> on your app's API configuration. Note that when updating this spec, the contract version is required to match the latest version of the API contract.
      security:
        - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/API'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /v1.0/app/samplesource:
    get:
      summary: Get your app's current participant source configuration
      tags:
        - Participant Source
      description: This returns your app's current participant source configuration. This consists of all the information required to configure a participant source in a survey, including entry link query parameters and exit link redirects. Overquota participants are participants who enter the survey, but their qualifications are over the set amount required for the survey. Terminated participants are participants who have been forcefully removed from the survey. Qualified participants are those who successfully complete the survey. Upon leaving the survey, based on the resolution of the participant (overquota, qualified, terminated), they will be redirected to the link indicated in this call. If a variable is required in an exit link, first it must be passed in via the entry link variable, and then referenced in the exit link with the following syntax ${variable_name}.
      security:
        - OAuth2: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantSource'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    patch:
      summary: Update a vendor's participant source attributes
      tags:
        - Participant Source
      description: This updates your app's current participant source configuration by performing a <a href="https://tools.ietf.org/html/rfc7396">JSON Merge Patch</a> of your app's current participant source configuration.
      security:
        - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantSource'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantSource'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: See https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token/
          scopes: {}
      x-tokenInfoFunc: demo.token_auth
    BasicAuth:
      type: http
      scheme: basic
      x-basicInfoFunc: demo.basic_auth
  schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    GetAppResponse:
      type: object
      properties:
        id:
          type: string
          example: hd6cb443h
          description: Generated ID for the partner
        name:
          type: string
          example: FVSupplier
          description: Name of the partner
          maxLength: 50
        status:
          type: string
          example: approved
          description: Status of the partner
          enum:
            - pending
            - approved
            - denied
            - inactive
        logo_link:
          type: string
          format: uri
          example: https://s3.partnerlogos.focusvision.com/somelogo.png
          description: Link to the current logo used for this vendor in the marketplace.
        marketing_text:
          type: string
          example: Quality sample at a quality price
          description: Text shown to users at the results page of the marketplace.
          maxLength: 240
        email:
          type: string
          format: email
          example: contact-us@email.com
          description: Contact email
        phone_number:
          type: string
          format: phone number
          example: 1-555-555-5555
          description: Contact phone number
    API:
      type: object
      properties:
        contract_version:
          type: number
          format: integer
          description: Version of the API Contract this API implements
          enum:
            - 1
          example: 1
        authentication:
          type: object
          description: OAuth2 client credentials flow
          properties:
            client_id:
              type: string
              example: l534nhacd9sdc
              description: Client id to use during authentication
            client_secret:
              type: string
              example: nc79wm2k4jbcus7ql2p4kxbhdh4842k
              description: Client secret to use during authentication
            token_link:
              type: string
              format: URI
              example: https://focusvision.com/fvsmp/oauth2/token
              description: URI used to obtain a token from via client credentials OAuth2 flow
        resources:
          type: object
          description: Endpoints for the different system resources
          properties:
            estimates:
              type: string
              format: URI
              example: https://focusvision.com/fvsmp/estimates
              description: URI used for the estimates resource
            projects:
              type: string
              format: URI
              example: https://focusvision.com/fvsmp/projects
              description: URI used for the projects resource
            samples:
              type: string
              format: URI
              example: https://focusvision.com/fvsmp/samples
              description: URI used for the samples resource
    ParticipantSource:
      type: object
      properties:
        exit_links:
          type: object
          description: Your app's exit links for redirecting survey participants
          properties:
            qualified:
              type: string
              format: url
              example: https://focusvision.com/callback?S=1&ID=${ID}
              description: Callback URL for qualified participants
            terminated:
              type: string
              format: url
              example: https://focusvision.com/callback?S=2&ID=${ID}
              description: Callback URL for terminated participants
            overquota:
              type: string
              format: url
              example: https://focusvision.com/callback?S=3&ID=${ID}
              description: Callback URL for overquota participants
        variables:
          type: object
          description: Any query parameters your app uses on survey entry links
          properties:
            unique:
              type: array
              items:
                type: string
              example:
                - ID
              description: Unique query parameter identifier's set on entry links
            required:
              type: array
              items:
                type: string
              example: []
              description: Required query parameter's provided on entry links
            extra:
              type: array
              items:
                type: string
              example: []
              description: Extra query parameter's provided on entry links
    response:
      type: object
      properties:
        access_token:
          type: string
          format: jwt
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.DjwRE2jZhren2Wt37t5hlVru6Myq4AhpGLiiefF69u8
          description: The issued access token
        token_type:
          type: string
          enum:
            - Bearer
          description: The type of the access token.
        expires_in:
          type: number
          example: 3600
          description: The lifetime in seconds of the access token.
    error:
      type: object
      properties:
        error:
          type: string
          description: Error code as specified in <a href="https://tools.ietf.org/html/rfc6749#section-5.2">IETF RFC-6749 Section-5.2</a>
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                description: Error code and message
                properties:
                  status:
                    type: string
                    description: HTTP status Code
                    enum:
                      - 401
                  message:
                    type: string
                    example: Unauthorized
                    description: Status message
                    enum:
                      - Unauthorized
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                description: Error code and message
                properties:
                  status:
                    type: string
                    description: HTTP status Code
                    enum:
                      - 500
                  message:
                    type: string
                    description: Status message
                    enum:
                      - Internal Server Error