Create new softwareType option for REST API's

[tomootes]

I've been in contact with people working within the Dutch Ministery Of Health about implementing pc.yml on their open source repo's.

Since they're open sourcing a lot of generic components they also have a lot of API's. Together we concluded that there is no perfect softwareType for API's.

Maybe we can introduce an option "standalone/REST_API" since it is so common nowadays?

@bzg / @bfabio

[dvh]

I'll give you a +1 if you change REST to HTTP (just like OpenAPI >= 3.1.0)

[jgroenen]

How about "standalone/backend - The software is a backend application."?

Of course this is not the best name, since "backend" implies "frontend" implies some sort of application specific backend (but this would be a contradiction with the "standalone" part).

But: a "standalone/backend" would (need to) have an API to be useful; so API is implied (which is the interface of the "backend").

In many cases, maybe instead of backend, "standalone/register" or "standalone/storage" would also be an option, but if you go that way, then "backend" maybe would have (too) many forms that only differ slightly.

[tomootes]

Totally agree on your reasoning Johan. standalone/backend could be seen as an option for this usecase. I'm trying to achieve a situation where it's easy to pick an option if your project is a Data-API or Service kind-of API. By this i mean any API which is not tied to a front-end.

As you state, the word backend implies that there is a front-end. I find it confusing that the option is called standalone/backend, since the word backend implies that it's not a standalone project 😆

[tomootes]

@dvh do you think its wise to make a disctinction between a service API and a Data API?

[tomootes]

@reinschaap @annejan @randh1r. What would you guys argue from your experience?

[annejan]

Current allowed vallues: "standalone/mobile", "standalone/iot", "standalone/desktop", "standalone/web", "standalone/backend", "standalone/other", "addon", "library", "configurationFiles"

And I agree with @tomootes that there is currently 4 main types: standalone, addon/plugin, library and configuration

A lot of modern projects have separate backand and frontend parts which makes the standalone a sub-optimal fit.
Adding separate "backend/http", "frontend/web" and more would probably make it easier.

Possibly in a matrix where backend, frontend and standalone before the slash and a list of options after the slash would be the most logical.

[jgroenen]

+1 for matrix; what are the two dimensions: "component type" (standalone, addon, plugin, library, config) and "interface type"?

[jgroenen]

component types: standalone, plugin, library, config, ...
interface types: web, cli, http, app, file, ...

makes me think of media types

[bfabio]

There's some overlap with platforms. Maybe the matrix could already be there as softwareType + platforms

[bfabio]

tl;dr: better description for "standalone/backend", deprecate "standalone/iot", add "``standalone/cli`"?

I always saw softwareType as a rough way to get a general idea of what's in the repo, not as something meant to be super precise about.

Personally, I’ve used "standalone/backend" for REST APIs. Maybe standalone/server would be a better name, not sure. But like @jgroenen said, maybe it's just a matter of improving the description of it.

To me an API is a backend. And a project doesn't have to include both backend and frontend in the same codebase. Frontends can totally be made by third parties. Think of a web server: it's clearly backend, the user agents aren't part of the same repo.

Looking at some real data: "standalone/other" is used 32 times (out of 473) in the Developers Italia catalog:

❯ publiccode-api-client software --publiccode-yml | grep softwareType | sort | uniq -c | sort -rn
    275   "softwareType": "standalone/web",
     60   "softwareType": "standalone/backend",
     41   "softwareType": "addon",
     32   "softwareType": "standalone/other",
     24   "softwareType": "library",
     19   "softwareType": "standalone/desktop",
     12   "softwareType": "standalone/mobile",
      6   "softwareType": "standalone/iot",
      3   "softwareType": "configurationFiles",

probably because people didn't know where to put their thing. That might tell us something.
From a quick glance it looks like they're either CLIs, Docker images or just mistakes. Is "standalone/cli" in order?

Also, now that we are at it: "standalone/iot" feels a bit off. Makes it look like we're going for very fine-grained categories, which I don't think is what we want.