OData OData Service API API

openapi: 3.0.3
info:
  title: OData Service OData Service API API
  description: OpenAPI specification for the OData (Open Data Protocol) standard service endpoints. OData is an OASIS standard that defines best practices for building and consuming RESTful APIs. It enables the creation of query-based data services over HTTP using standard conventions for resource identification, URL construction, and payload formats.
  version: '4.01'
  contact:
    name: OASIS OData Technical Committee
    url: https://www.odata.org/
  license:
    name: OASIS Open
    url: https://www.oasis-open.org/policies-guidelines/ipr/
servers:
- url: https://services.odata.org/V4/TripPinService
  description: OData TripPin Reference Service
- url: '{serviceRoot}'
  description: Custom OData Service Root
  variables:
    serviceRoot:
      default: https://localhost/odata
      description: The root URL of the OData service
tags:
- name: OData Service API
paths:
  /:
    get:
      operationId: getServiceDocument
      summary: OData Get Service Document
      description: Returns the OData service document, which lists all available entity sets, singletons, and function imports exposed by the service.
      parameters:
      - $ref: '#/components/parameters/ODataVersion'
      - $ref: '#/components/parameters/Accept'
      responses:
        '200':
          description: Service document returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - OData Service API
  /{entitySet}:
    get:
      operationId: getEntityCollection
      summary: OData Query Entity Collection
      description: Retrieves a collection of entities from the specified entity set. Supports OData system query options for filtering, sorting, pagination, and projection.
      parameters:
      - name: entitySet
        in: path
        required: true
        description: Name of the entity set to query
        schema:
          type: string
      - $ref: '#/components/parameters/ODataVersion'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Expand'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/Search'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Entity collection returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - OData Service API
    post:
      operationId: createEntity
      summary: OData Create Entity
      description: Creates a new entity in the specified entity set.
      parameters:
      - name: entitySet
        in: path
        required: true
        description: Name of the entity set
        schema:
          type: string
      - $ref: '#/components/parameters/ODataVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Entity data conforming to the entity type schema
      responses:
        '201':
          description: Entity created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflict - entity already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODataError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - OData Service API
  /{entitySet}({key}):
    get:
      operationId: getEntity
      summary: OData Get Entity by Key
      description: Retrieves a single entity by its key value.
      parameters:
      - name: entitySet
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        description: The key value identifying the entity
        schema:
          type: string
      - $ref: '#/components/parameters/ODataVersion'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: Entity returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - OData Service API
    patch:
      operationId: updateEntity
      summary: OData Update Entity
      description: Updates an existing entity using PATCH (merge semantics).
      parameters:
      - name: entitySet
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ODataVersion'
      - name: If-Match
        in: header
        description: ETag value for optimistic concurrency control
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Entity updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '204':
          description: Entity updated successfully (no content)
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: Precondition failed - ETag mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODataError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - OData Service API
    delete:
      operationId: deleteEntity
      summary: OData Delete Entity
      description: Deletes an entity from the specified entity set.
      parameters:
      - name: entitySet
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ODataVersion'
      - name: If-Match
        in: header
        description: ETag value for optimistic concurrency control
        schema:
          type: string
      responses:
        '204':
          description: Entity deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: Precondition failed - ETag mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODataError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - OData Service API
components:
  parameters:
    Select:
      name: $select
      in: query
      description: Comma-separated list of properties to include
      schema:
        type: string
      example: Name,Age
    Expand:
      name: $expand
      in: query
      description: Related entities to include inline
      schema:
        type: string
      example: Orders
    Search:
      name: $search
      in: query
      description: Free-text search expression
      schema:
        type: string
    ODataVersion:
      name: OData-Version
      in: header
      description: OData protocol version
      schema:
        type: string
        enum:
        - '4.0'
        - '4.01'
        default: '4.01'
    Format:
      name: $format
      in: query
      description: Response format override
      schema:
        type: string
        enum:
        - json
        - xml
    Top:
      name: $top
      in: query
      description: Maximum number of entities to return
      schema:
        type: integer
        minimum: 0
    Accept:
      name: Accept
      in: header
      schema:
        type: string
        default: application/json
    Count:
      name: $count
      in: query
      description: Whether to include a count of matching entities
      schema:
        type: boolean
    OrderBy:
      name: $orderby
      in: query
      description: Property and direction for sorting
      schema:
        type: string
      example: Name asc
    Skip:
      name: $skip
      in: query
      description: Number of entities to skip
      schema:
        type: integer
        minimum: 0
    Filter:
      name: $filter
      in: query
      description: OData filter expression to restrict returned entities
      schema:
        type: string
      example: Name eq 'Smith'
  schemas:
    Entity:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.etag':
          type: string
          description: ETag for concurrency control
        '@odata.id':
          type: string
          description: Entity ID URL
        '@odata.editLink':
          type: string
          description: URL for editing the entity
        '@odata.type':
          type: string
          description: Fully qualified entity type name
      additionalProperties: true
    ServiceDocumentItem:
      type: object
      required:
      - name
      - url
      properties:
        name:
          type: string
          description: Name of the entity set, singleton, or function import
        kind:
          type: string
          enum:
          - EntitySet
          - Singleton
          - FunctionImport
          - ServiceDocument
          description: Kind of resource
        url:
          type: string
          description: URL relative to the service root
    EntityCollection:
      type: object
      required:
      - value
      properties:
        '@odata.context':
          type: string
          description: Context URL describing the entity type
        '@odata.count':
          type: integer
          description: Total count of matching entities (if requested)
        '@odata.nextLink':
          type: string
          format: uri
          description: URL to the next page of results
        '@odata.deltaLink':
          type: string
          format: uri
          description: URL to track changes from this point
        value:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
    ODataError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Service-defined error code
            message:
              type: string
              description: Human-readable error message
            target:
              type: string
              description: Target of the error (e.g., property name)
            details:
              type: array
              items:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  target:
                    type: string
            innererror:
              type: object
              description: Service-defined inner error details
              additionalProperties: true
    ServiceDocument:
      type: object
      required:
      - '@odata.context'
      - value
      properties:
        '@odata.context':
          type: string
          description: Context URL pointing to the metadata document
          example: https://services.odata.org/V4/TripPinService/$metadata
        value:
          type: array
          items:
            $ref: '#/components/schemas/ServiceDocumentItem'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request - invalid query or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
externalDocs:
  description: OData Version 4.01 Specification
  url: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html