github.com/pelicanplatform/pelican@v1.0.5/web_ui/frontend/app/api/docs/pelican-swagger.yaml (about)

     1  swagger: '2.0'
     2  info:
     3    title: Pelican Server APIs
     4    description: "[Pelican](https://pelicanplatform.org/) provides an open-source software platform for federating 
     5        dataset repositories together and delivering the objects to computing capacity such as the [OSPool](https://osg-htc.org/services/open_science_pool.html)
     6  
     7  
     8        This is the API documentation for various APIs in Pelican servers (director, registry, origin, etc) 
     9        to communicate with each other and in-between users accessing the servers. 
    10        
    11  
    12        For how to set up Pelican servers, please refer to the documentation at [docs.pelicanplatform.org](https://docs.pelicanplatform.org/)"
    13    license:
    14      name: Apache 2.0
    15      url: http://www.apache.org/licenses/LICENSE-2.0
    16    contact:
    17      name: API Support via Pelican GitHub Issue
    18      url: https://github.com/PelicanPlatform/pelican/issues
    19    version: '1.0'
    20  basePath: /api/v1.0/
    21  consumes:
    22    - application/json
    23  produces:
    24    - application/json
    25  schemes:
    26    - https
    27  securityDefinitions:
    28    # This is a hacky way to specify Bearer token auth here because it's not actually an "apikey"
    29    Bearer:
    30      type: apiKey
    31      name: Authorization
    32      in: header
    33      description: >-
    34        Enter the JWT with the `Bearer` prefix, e.g. "Bearer abcde12345".
    35  definitions:
    36    HealthStatus:
    37      type: object
    38      description: The health status of a server component
    39      properties: 
    40        status:
    41          type: string
    42          description: The status of the component, can be one of "unknown", "warning", "ok", and "critical"
    43          example: warning
    44        message:
    45          type: string
    46          description: Optional message to describe the status
    47          example: ""
    48        last_update:
    49          type: integer
    50          description: Int64 unix time of the last status update
    51          example: 1700594867
    52      readOnly: true
    53    ErrorModel:
    54      type: object
    55      description: The error reponse of a request
    56      properties: 
    57        error:
    58          type: string
    59          description: The detail error message
    60          example: Authentication required to perform this operation
    61    SuccessModel:
    62      type: object
    63      description: The successful reponse of a request
    64      properties: 
    65        msg:
    66          type: string
    67          description: The detail success message
    68          example: Success
    69  tags:
    70    - name: auth
    71      description: Authentication APIs for all servers
    72    - name: common
    73      description: Common APIs for all servers
    74  paths:
    75    /health:
    76      get:
    77        tags:
    78          - common
    79        summary: Returns the health status of server components
    80        produces:
    81          - application/json
    82        security:
    83          - Bearer: []
    84        responses:
    85          '200':
    86            description: OK
    87            schema:
    88              type: object
    89              properties:
    90                status:
    91                  type: string
    92                  description: The overall health status of the server
    93                components:
    94                  type: object
    95                  description: The health status of each server components
    96                  properties: 
    97                    cmsd:
    98                      $ref: '#/definitions/HealthStatus'
    99                    federation:
   100                      $ref: '#/definitions/HealthStatus'
   101                    web-ui:
   102                      $ref: '#/definitions/HealthStatus'
   103                    xrootd:
   104                      $ref: '#/definitions/HealthStatus'
   105    /config:
   106      get:
   107        tags:
   108          - common    
   109        summary: Return the configuration values of the server
   110        produces:
   111        - application/json
   112        security:
   113          - Bearer: []
   114        responses:
   115          '200':
   116            description: OK
   117            schema:
   118              type: object
   119              description: The JSON object output from viper with all config values in the current server
   120          '401':
   121            description: Unauthorized
   122    /auth/login:
   123      post:
   124        tags:
   125          - auth    
   126        summary: Login with username and password to Pelican web UI
   127        consumes:
   128        - application/json
   129        produces:
   130        - application/json
   131        parameters:
   132          - in: body
   133            name: userCredential
   134            description: The username and password to authenticate
   135            schema:
   136              type: object
   137              required:
   138                - user
   139                - password
   140              properties: 
   141                user:
   142                  type: string
   143                password:
   144                  type: string
   145        responses:
   146          '200':
   147            description: Login succeed
   148            schema:
   149              type: object
   150              $ref: "#/definitions/SuccessModel"          
   151          '400':
   152            description: Invalid request, when username or password is missing
   153            schema:
   154              type: object
   155              $ref: "#/definitions/ErrorModel"          
   156          '401':
   157            description: Login failed, when username or password doesn't match the record
   158            schema:
   159              type: object
   160              $ref: "#/definitions/ErrorModel"
   161    /auth/initLogin:
   162      post:
   163        tags:
   164          - auth        
   165        summary: Login with one-time activation code to initialize web UI
   166        consumes:
   167        - application/json
   168        produces:
   169        - application/json
   170        parameters:
   171          - in: body
   172            name: activationCode
   173            description: The 6-digit code used to initialize web UI
   174            schema:
   175              type: object
   176              required:
   177                - code
   178              properties: 
   179                code:
   180                  type: string
   181                  example: "123456"
   182        responses:
   183          '200':
   184            description: Login succeed
   185            schema:
   186              type: object
   187              $ref: "#/definitions/SuccessModel"          
   188          '400':
   189            description: Invalid request, when authentication is already initialized, 
   190              code-based login is not available, or login code is not provided
   191            schema:
   192              type: object
   193              $ref: "#/definitions/ErrorModel"          
   194          '401':
   195            description: Login failed, when code is not valid
   196            schema:
   197              type: object
   198              $ref: "#/definitions/ErrorModel"
   199    /auth/resetLogin:
   200      post:
   201        tags:
   202          - auth        
   203        summary: Reset the password for the user
   204        consumes:
   205        - application/json
   206        produces:
   207        - application/json
   208        security:
   209          - Bearer: []
   210        parameters:
   211          - in: body
   212            name: newPassword
   213            description: The new password to reset to
   214            schema:
   215              type: object
   216              required:
   217                - password
   218              properties: 
   219                password:
   220                  type: string
   221                  description: The new password to reset to
   222                  example: ""
   223        responses:
   224          '200':
   225            description: Reset succeed
   226            schema:
   227              type: object
   228              $ref: "#/definitions/SuccessModel"          
   229          '400':
   230            description: Invalid request request, when password is missing
   231            schema:
   232              type: object
   233              $ref: "#/definitions/ErrorModel"          
   234          '500':
   235            description: Server-side error, when failed to write the new password to auth file
   236            schema:
   237              type: object
   238              $ref: "#/definitions/ErrorModel"            
   239          '403':
   240            description: Unauthorized request, when user is not logged in
   241            schema:
   242              type: object
   243              $ref: "#/definitions/ErrorModel"
   244    /auth/whoami:
   245      get:
   246        tags:
   247          - auth    
   248        summary: Return the authentication status of the web ui
   249        produces:
   250        - application/json
   251        responses:
   252          '200':
   253            description: OK
   254            schema:
   255              type: object
   256              description: The authentication status and username, if any. "user" field is omitted
   257                when "authenticated" is false
   258              properties: 
   259                authenticated:
   260                  type: boolean
   261                  example: true
   262                user:
   263                  type: string
   264                  example: "admin"
   265    /auth/loginInitialized:
   266      get:
   267        tags:
   268          - auth    
   269        summary: Return the status of web UI initialization
   270        description: The initialization depends on if the user has used the one-time activation
   271          code to set up the password for the admin user
   272        produces:
   273        - application/json
   274        responses:
   275          '200':
   276            description: OK
   277            schema:
   278              type: object
   279              description: The initialization status
   280              properties: 
   281                initialized:
   282                  type: boolean
   283                  example: true