Can OpenAPI integrate HATEOAS in a useful way?

Question

Is it possible to describe a HATEOAS REST API with OpenAPI?

When I describe the API in HAL Format I would need to define three schemas for it (one for Request Payloads, one for Collection Resource and one for Item Resource). For Example:

components:
  schemas:
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean
    Links:
      type: object
      discriminator:
        propertyName: _links
      properties:
        _links:
          type: object
          additionalProperties:
            type: string
            $ref: "#/components/schemas/Link"
    CollectionModel:
      type: object
      discriminator:
        propertyName: _embedded
      properties:
        _embedded:
          type: object
        _links:
          type: object
          properties:
            self:
              type: string
            profile:
              type: string
            search:
              type: string
    CollectionModel_Foo:
      type: object
      allOf:
        - $ref: "#/components/schemas/CollectionModel"
      properties:
        _embedded:
          type: object
          properties:
            projects:
              type: array
              items:
                $ref: "#/components/schemas/EntityModel_Foo"
    EntityModel_Foo:
      type: object
      allOf:
        - $ref: "#/components/schemas/Foo"
        - $ref: "#/components/schemas/Links"
    Foo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        bar:
          type: string

I don't find that very useful because that complicates the specification and since when generating a client based on that schema using OpenAPI Generator the client does not pay attention to HATEOAS and simply requests the resources. So in this context it is useless.

I thought about implementing JSON:API but sadly the full JSON Schema is only supported in the current OpenAPI 3.1 draft.

All in all I can't find a proper way to integrate OpenAPI in a HATEOAS API.

Pozzy

Didn't find a solution to this question, but the Zalando API Guidelines discuss a similar Problem regarding HATEOAS and refer to OpenAPI in this discussion. – Pozzy

I think the openapi generator has no use for hateoas, to use it you need someting like this: github.com/badgateway/ketting – Karly

Answer 1

I'm going to expand a bit on what @wutzebaer said.

OpenAPI doesn't really mesh with the HATEOAS because OpeAPI knows all of the urls and how to make them. HATEOAS as an idea says that a client (a human using a web browser) should be able to move around using nothing more that it's expert knowledge and links on the screen. OpenAPI is RPC over HTTP. It will make the URLs provided you know all the meta data to fill in the templates.

For example, HATEOAS might say, '/users/123-123' will get you the user. OpenAPI knows '/user/:userID' will get you the user. It will generate a function on a class that says getUser(UserID). OpenAPI deals with concrete ideas, what HATEAOS requires abstract thinking.

If you use OpenAPI, an implicit assumption is that you're code generating the client. Once you do that, you are stuck with (for better or worse) the system's abstractions.

Precession