search

NLeSC / guide

Software Development Guide
https://guide.esciencecenter.nl
Creative Commons Attribution 4.0 International
46 stars 30 forks source link

api design guide #54

Open mkuzak opened 7 years ago

mkuzak commented 7 years ago

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 commented 7 years ago

Specifically web APIs, or APIs in general?

mkuzak commented 7 years ago

http APIs

mkuzak commented 7 years ago

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

mkuzak commented 7 years ago

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

c-martinez commented 4 years ago

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

egpbos commented 11 months ago

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 commented 11 months ago

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 :smile:.

egpbos commented 11 months ago

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

LourensVeen commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

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...).

bouweandela commented 6 days ago

Potentially relevant: https://fastapi.tiangolo.com/

sverhoeven commented 6 days ago

Also https://jsonapi.org/ which has conventions on JSON shape and https://datatracker.ietf.org/doc/html/rfc9457 on error reporting.