More examples on microtypes

[lsmag]

Hi!

I'm trying to digest this document. Googling around, I found this presentation and this website, both shedding some light on MicroTypes. However, I'm still not getting the information I'm looking for, and the introspected REST document keeps info around microtypes fairly general/abstract. The MicroTypes website I linked to also appears to be incomplete, since the "Available MicroTypes" section doesn't really suggest anything.

What I think would be useful is documentation on current microtypes (the ones you referred to in the links above and this document, for example), how to introduce a new microtype, that kind of thing.

I'm particularly curious about the "deprecation" microtype, I don't think I saw an example of it anywhere. Deprecating things (fields and/or URLs) is a major part of API maintenance, and I'm curious whether introspected REST has a way to communicating it (like JSON-Schema has been discussing signaling fields as deprecated).

Finally, how would you think we should do API versioning? I imagine something like api-version=X.Y would work, but are there any other ideas floating around?

[vasilakisfil]

Hi @lsmag, sorry for late reply. Unfortunately I don't have time to finish the microtypes.info website but will probably do beginning of next month. Here and in microtypes.info, I mostly present the concept of it. Rigid Microtypes will probably come next year.

Regarding deprecation, this could be a MicroType or you could just use the JSON Schema for it. I feel like the JSON Schema falls in the same concept as MicroTypes, only the announcement is made different: just a describedBy link in the Link header. However, in this case you take what the server provides you, no space for negotiating the JSON schema version. If you use a (wrapper) MicroType for that you could even negotiate for that.

I think API versioning should only take place when it's mandatory. I mean, with REST and even more with Introspected REST + MicroTypes, your content should be descriptive and rarely comes the need for breaking changes. If however, you need a breaking change (usually a semantic breaking change), that would trigger a completely new API version from your side. Both URL versioning or Media Type versioning is equally good for REST/Introspected REST, although in theory the Media Type is the correct place to apply versioning since it's where the API semantics are described.