[Koha-bugs] [Bug 15126]=?UTF-8?Q?=20REST=C2=A0API?=: Use newer version of Swagger2

[bugzilla-daemon at bugs.koha-community.org]

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=15126

Olli-Antti Kivilahti <olli-antti.kivilahti at jns.fi> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |olli-antti.kivilahti at jns.fi

--- Comment #5 from Olli-Antti Kivilahti <olli-antti.kivilahti at jns.fi> ---
Hi!

I think your solution looks robust and extendable. I would push the separation
of definitions a bit further.
This is a good article about how to split the Swagger2-spec:
    http://azimi.me/2015/07/16/split-swagger-into-smaller-files.html
and it is pretty much the same as you did.

How about we modified your suggestion so the structure looks like this:

.
├── swagger.json
├── info
│   └── index.json
├── definitions
│   └── index.json
│   └── error.json
│   └── patron.json
├── parameters
│   └── index.json
│   └── patron.json
└── paths
    ├── index.json
    └── patrons.json

where definitions/patron.json looks like this:
    "borrower": {
      "type": "object",
      "properties": {
        "borrowernumber": {
          "$ref": "#/definitions/borrowernumber"
        },
        "cardnumber": {
          "$ref": "#/definitions/cardnumber"
        },
        "surname": {
          "$ref": "#/definitions/surname"
        },
        "firstname": {
          "$ref": "#/definitions/firstname"
        },
        ...
      }
    },
    "cardnumber": {
      "description": "Library assigned ID number for Borrowers",
      "type": "string"
    },
    "borrowernumber": {
      "type": "integer",
      "description": "Borrower internal identifier"
    },
    "surname": {
      "description": "borrower's last name",
      "type": "string"
    },
    "surname": {
      "description": "borrower's first name",
      "type": "string"
    }

Now that there is a clear separation of logic (and release from insanely
obscure git conflict resolutions with swagger.json), we should enforce that we
define all parameters and definitions globally under #/parameters and
#/definitions instead of defining them under object/path definitions.
This way we maximize code reuse.
In some cases it might not make much sense (if we only focus on today), like
for "surname" and "firstname" in the above example, but some day in the near
future somebody might want to reuse those components and then he would have to
refactor those changes (or more likely just duplicate code because we are
lazy). So as a future-proof solution I feel global definitions are the way to
go.

We could even push this a bit further, by instead of defining these REST API
with the restrictions of the Koha DB, we could use commonly acknowledged linked
data schemas, like schema.org to define our objects.
https://schema.org/Person
This would make it much easier to share the same records, for example between
multiple Koha installations. Mainly because of the unique identifier in these
objects, like {"url": "https://renki.vaarakirjastot.fi/api/v1/patrons/43441"}
This is actually something which is easily enabled due to our awesome REST API
and helps build more linked data systems between various API consumers.
So if somebody would take our Patron-object, it would have a undeniably unique
identifier and wouldn't conflict with Patron-objects originating from other
systems.

But for now we can focus on splitting our Swagger-spec.

-- 
You are receiving this mail because:
You are watching all bug changes.