swagger.yaml

swagger: '2.0'
info:
  title: OSU Directory Web API
  description: Search LDAP directory entries.
  version: "1"
  license:
    name: GNU Affero General Public License Version 3
    url: http://www.gnu.org/licenses/agpl-3.0.en.html
externalDocs:
  description: GitHub Repository
  url: https://github.com/osu-mist/directory-api
host: api.oregonstate.edu
schemes:
  - https
basePath: /v1
produces:
  - application/json
security:
  - OAuth2:
    - full
paths:
  /directory:
    get:
      tags:
        - directory
      operationId: getBySearchQuery
      description: Get entries in directory matching all terms in search query
      produces:
        - application/json
      parameters:
        - name: q
          in: query
          description: |
            For basic directory searches. Searches by username, full name,
            and email address.
          type: string
          required: false
        - name: primaryAffiliation
          in: query
          description: Filter by primary affiliation
          type: string
          required: false
          enum:
            - Employee
            - Other
            - Retiree
            - Student
            - Unknown
        - name: lastName
          in: query
          description: Filter by last name
          type: string
          required: false
        - name: emailAddress
          in: query
          description: Filter by email address
          type: string
          required: false
        - name: officePhoneNumber
          in: query
          description: Filter by office phone number
          type: string
          required: false
        - name: alternatePhoneNumber
          in: query
          description: Filter by alternate phone number
          type: string
          required: false
        - name: homePhoneNumber
          in: query
          description: Filter by home phone number
          type: string
          required: false
        - name: phoneNumber
          in: query
          description: Filter by any phone number
          type: string
          required: false
        - name: faxNumber
          in: query
          description: Filter by fax number
          type: string
          required: false
        - name: officeAddress
          in: query
          description: Filter by office address
          type: string
          required: false
        - name: department
          in: query
          description: Filter by department
          type: string
          required: false
        - $ref: '#/parameters/pretty'
      responses:
        "200":
          description: Array of directory entities
          schema:
            type: array
            items:
              $ref: "#/definitions/ResultObject"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/Error"
  /directory/{osuuid}:
    get:
      tags:
      - directory
      operationId: getByOSUUID
      description: Get entries in directory filtered by query parameters
      parameters:
        - name: osuuid
          in: path
          description: "OSUUID of the person to be fetched."
          type: integer
          format: int64
          required: true
        - $ref: '#/parameters/pretty'
      responses:
        "200":
          description: Directory entity
          schema:
           $ref: "#/definitions/ResultObject"
        "404":
          description: Not found
          schema:
            $ref: "#/definitions/Error"
parameters:
  pretty:
    name: pretty
    in: query
    type: boolean
    required: false
    description: If true, JSON response will be pretty-printed
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: https://api.oregonstate.edu/oauth2/token
    scopes:
      full: Full access to the API
definitions:
  ResultObject:
    properties:
      data:
        type: array
        items:
          $ref: "#/definitions/ResourceObject"
  ResourceObject:
    properties:
      id:
        type: integer
      type:
        type: string
        example: "directory"
      attributes:
        $ref: "#/definitions/Attributes"
      links:
        $ref: "#/definitions/ResourceLinks"
  Attributes:
    properties:
      firstName:
        type: string
      lastName:
        type: string
      fullName:
        type: string
      primaryAffiliation:
        type: string
      jobTitle:
        type: string
      department:
        type: string
      departmentMailingAddress:
        type: string
      homePhoneNumber:
        type: string
      homeAddress:
        type: string
      officePhoneNumber:
        type: string
      officeAddress:
        type: string
      faxNumber:
        type: string
      emailAddress:
        type: string
        format: email
      username:
        type: string
      alternatePhoneNumber:
        type: string
      osuuid:
        type: integer
        format: int64
  ResourceLinks:
    properties:
      self:
        type: string
  Error:
    type: object
    properties:
      status:
        type: integer
        format: int32
        description: HTTP status code.
      developerMessage:
        type: string
        description: An error string aimed at developers.
      userMesage:
        type: string
        description: An error string aimed at end users.
      code:
        type: integer
        description: Error code.
      details:
        type: string
        description: A link to further information about the error.