swagger.yml

---
swagger: '2.0'
info:
  version: 0.0.1
  title: Rialto Entity Resolver
securityDefinitions:
  key:
    type: apiKey
    in: header
    name: X-API-Key
paths:
  /topic:
    get:
      produces:
        - text/plain
      parameters:
        - name: name
          required: true
          type: string
          in: query
          description: Name of the topic
      security:
        - key: []
      operationId: FindTopic
      responses:
        200:
          description: returns a URI for the topic in RIALTO
          schema:
            type: string
            description: contains the actual URI
        404:
          description: Topic not found
          schema:
            $ref: "#/definitions/ErrorResponse"
        500:
          description: Server error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /grant:
    get:
      produces:
        - text/plain
      parameters:
        - name: identifier
          required: true
          type: string
          in: query
          description: A grant identifier
      security:
        - key: []
      operationId: FindGrant
      responses:
        200:
          description: returns a URI for the grant in RIALTO
          schema:
            type: string
            description: contains the actual URI
        404:
          description: Grant not found
          schema:
            $ref: "#/definitions/ErrorResponse"
        500:
          description: Server error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /organization:
    get:
      produces:
        - text/plain
      parameters:
        - name: name
          required: true
          type: string
          in: query
          description: Name of the organization
        - name: country
          required: false
          type: string
          in: query
          description: The country that this organization is in.
      security:
        - key: []
      operationId: FindOrganization
      responses:
        200:
          description: returns a URI for the organization in Rialto
          schema:
            type: string
            description: contains the actual URI
        404:
          description: Organization not found
          schema:
            $ref: "#/definitions/ErrorResponse"
        500:
          description: Server error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /person:
    get:
      produces:
        - text/plain
      parameters:
        - name: first_name
          required: false
          type: string
          in: query
          description: First name of the person
        - name: full_name
          required: false
          type: string
          in: query
          description: Full name of the person
        - name: last_name
          required: false
          type: string
          in: query
          description: Last name of the person
        - name: orcid
          required: false
          type: string
          in: query
          description: ORCID of the person
        - name: sunetid
          required: false
          type: string
          in: query
          description: SUNet ID of the person
      security:
        - key: []
      operationId: findPerson
      responses:
        200:
          description: returns a URI for the person in Rialto
          schema:
            type: string
            description: contains the actual URI
        404:
          description: Person not found
          schema:
            $ref: "#/definitions/ErrorResponse"
        500:
          description: Server error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /healthcheck:
    get:
      produces:
        - application/json
      operationId: healthCheck
      responses:
        200:
          description: The service is working properly
          schema:
            $ref: "#/definitions/HealthCheckResponse"
        503:
          description: The service is not working properly
          schema:
            $ref: "#/definitions/HealthCheckResponse"
definitions:
  HealthCheckResponse:
    type: object
    properties:
      status:
        type: string
        description: "The status of the service"
    example:
      status: "OK"
  ErrorResponse:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: "#/definitions/Error"
  Error:
    type: object
    properties:
      title:
        type: string
        description: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem.
        example: Invalid Attribute
      detail:
        type: string
        description: a human-readable explanation specific to this occurrence of the problem.
        example: Title must contain at least three characters.
      status:
        type: string
        description:  the HTTP status code applicable to this problem, expressed as a string value.
        example: 404