openapi: 3.0.3
info:
  title: SharePoint REST Files Lists API
  description: The SharePoint REST API enables developers to interact remotely with SharePoint data using any technology that supports REST web requests. Provides CRUD operations on sites, lists, items, files, folders, permissions, and user profiles using OData protocol standards.
  version: '1.0'
  x-generated-from: documentation
  contact:
    name: Microsoft
    url: https://learn.microsoft.com/en-us/sharepoint/dev/
servers:
- url: https://{site_url}/_api
  description: SharePoint REST API endpoint
  variables:
    site_url:
      default: contoso.sharepoint.com/sites/mysite
      description: SharePoint site URL
tags:
- name: Lists
  description: List and library operations
paths:
  /web/lists:
    get:
      operationId: getLists
      summary: SharePoint Get Lists
      description: Retrieve all lists on the current site.
      tags:
      - Lists
      parameters:
      - name: $select
        in: query
        schema:
          type: string
        description: Properties to return.
      - name: $filter
        in: query
        schema:
          type: string
        description: OData filter expression.
      - name: $top
        in: query
        schema:
          type: integer
        description: Maximum results to return.
        example: 10
      responses:
        '200':
          description: Collection of lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCollection'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createList
      summary: SharePoint Create List
      description: Create a new list on the current site.
      tags:
      - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCreateRequest'
      responses:
        '201':
          description: List created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /web/lists/getbytitle('{list_title}'):
    get:
      operationId: getListByTitle
      summary: SharePoint Get List by Title
      description: Retrieve a list by its title.
      tags:
      - Lists
      parameters:
      - name: list_title
        in: path
        required: true
        schema:
          type: string
        description: Title of the list.
        example: Documents
      responses:
        '200':
          description: List metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    List:
      type: object
      description: SharePoint list or document library.
      properties:
        Id:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        Title:
          type: string
          example: Documents
        Description:
          type: string
          example: Shared documents library
        BaseTemplate:
          type: integer
          example: 101
        ItemCount:
          type: integer
          example: 42
        Created:
          type: string
          format: date-time
          example: '2024-01-15T12:00:00Z'
        LastItemModifiedDate:
          type: string
          format: date-time
        Hidden:
          type: boolean
          example: false
        EnableVersioning:
          type: boolean
          example: true
    ListCreateRequest:
      type: object
      description: Request to create a new SharePoint list.
      required:
      - Title
      - BaseTemplate
      properties:
        __metadata:
          type: object
          properties:
            type:
              type: string
              example: SP.List
        Title:
          type: string
          example: My New List
        Description:
          type: string
          example: A custom list
        BaseTemplate:
          type: integer
          example: 100
          description: 100=Generic List, 101=Document Library, 104=Announcements
        AllowContentTypes:
          type: boolean
          example: true
        ContentTypesEnabled:
          type: boolean
          example: true
    ListCollection:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/List'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 via Azure AD / Microsoft Identity Platform.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            Sites.Read.All: Read all site collections.
            Sites.ReadWrite.All: Read and write all site collections.
            Sites.Manage.All: Create, edit, and delete items and lists.
            Sites.FullControl.All: Full control of all site collections.