HATEOAS and Swift OpenAPI generator

Related Projects
1

Hi everyone,

We're experimenting with the Swift OpenAPI generator. Now we have an OpenAPI spec that uses the HATEOAS - Wikipedia pattern. Thus it contains links from resources to other resources and valid state changes. For instance the /api/things endpoint contains links to both detail /api/things/{id} as well as a link to the create endpoint:

{
    "things": [
        {
            "id": 123456
            "name": "thing1",
            ...
            "links": [
                {
                    "href": "/things/123456"   <-- detail info for this 'thing'
                },
            ]
        },
        {
            "id": 42
            "name": "thing2",
            ...
            "links": [
                {
                    "href": "/things/42"
                },
            ]
        }
    ],
    "links": [
        {
            "href": "/things",   <-- creates a new 'thing'
            "method": "POST"
        }
    ]
}

Is there a way of generating these from the OpenAPI generator directly? Or do we need to write our own logic to create these links?

3

Hi @maartene - do you have a public example of such an OpenAPI doc? I'm curious where the line would be drawn between the statically known vs dynamic at runtime information.

I'm especially curious if the links can point to any arbitrary resources, or if they always point to a statically known type and the ask here is mainly about extracting e.g. the identifier of the resource, and being able to access it using this "chained" approach.

Knowing this will help me provide a better answer of whether Swift OpenAPI Generator supports, or could support it.

4

Hi @Honza_Dvorsky,

Here's the example we're using right now: iCloud Drive - Apple iCloud

BTW: I don't expect we'd expect to generate all types of links - especially when it comes to links representing state changes. However, for basic CRUD like operations and/or going from collection -> single, those might be relevant.

5

So out of the box, Swift OpenAPI Generator won't do anything special - it just generates the schemas from the OpenAPI document.

You could file an issue on the repo and illustrate the type of code you'd find useful if it were generated. Ideally it's use vanilla features from the OpenAPI specification - we don't generally add non-spec-compliant add-ons, but maybe there are some extension hooks we could open up.

1 Like
6

Thank you @Honza_Dvorsky

I'll first check if there is a canonical way the OpenAPI spec expects us do this. If there isn't, I'll consider it out of scope for OpenAPI and therefore also for the Swift OpenAPI Generator.

KR Maarten