api design guide

[mkuzak]

There should be something in the guide about good API design. I would point to https://geemus.gitbooks.io/http-api-design/content/en/ and swagger.io
The problem I have is I don't know where to put it. It could go together with language guides.

[LourensVeen]

Specifically web APIs, or APIs in general?

[mkuzak]

http APIs

[mkuzak]

We've already been thinking about some kind of web dev guide section. It should go there.

[mkuzak]

this is actually a great guide:
https://cloud.google.com/apis/design/

[c-martinez]

Is this something which could be included somewhere in the turing way? Or where would this fit in our guide?

[egpbos]

It took some digging, but there is something about UI design in the Turing Way: https://the-turing-way.netlify.app/collaboration/stakeholder-engagement.html?highlight=user#user-centric-design

API design is, admittedly a different thing still, but my thinking was: these both fall into a broader category of user-interfaces (for APIs the users are just more technical). The Turing Way addresses that broad topic, although, I must say, quite shallowly... Quickly browsing the Turing Way's menu didn't give me any hints that there was anything about users at all! A bit surprising for such a huge book. Software isn't only about development, right? 😄

Maybe the difficulty is, though, that while there are probably some generic guidelines, the specifics of APIs depend a lot on the language you use, and similarly the specifics of UIs and UX depend on what framework you use.

Ok, anyway, I'm not yet sure how to proceed with this. If someone wants to take a stab at a chapter like this, I would suggest that they first try writing a quick draft with some rudimentary structure and thoughts. Preferably do some brainstorming first, say with two or three people. Don't write actual text yet, let's first discuss the potential contents a bit further before deciding whether a chapter on this makes sense.

[LourensVeen]

The Turing Way, like our Guide, is written by scientists, and real science is curiosity driven. So it's no surprise to me that there's no mention of users. As I've said before, software begins and ends with people. Actually, engineering begins and ends with people, but science doesn't. Science starts with a research question and ends with a paper, and in between is a script. So there we are.

I don't think API design is all that language-specific. You can probably split APIs in type-chaotic and intended for consumption by end users from a REPL or a script (most R packages, and also Python packages in the same data science space), and more engineered, typed and intended to program against. These days the latter are almost invariably somewhat object oriented, even in languages that don't support OO (the Linux kernel is heavily OO for example, even though it's written in C). So I think there's something more general to be said about how to design a good API. I've added it to my list of potential future TEC topics 😄.

[egpbos]

Is there something on this in the internal training programme actually? Might make sense there...

[LourensVeen]

Oh there is actually, Module 1 Unit 6. I haven't looked at it yet, but there's a link to a freeCodeCamp.org tutorial, a book chapter about REST and a RedHat advertising piece that takes a devops-oriented approach to web APIs.

It's all about REST it seems, nothing about designing libraries for programming against.

[c-martinez]

I agree with @egpbos that maybe some brainstorming and rough outline should come before writing any significant amount of text. I would suggest that that discussion could be an issue at The Turing Way, if we want to add out final contribution there (which I think we do, since it is not very eScience Center specific).

[egpbos]

Note btw that it's even possible to get KD budget for this brainstorming / research phase, as the Java KD project shows (a news message about the awarded KD projects is coming soon...).