For authentication do I really need to go the whole OAuth 2 route or
can API keys be enough?
I don't want to rock the boat as opinions seem to be divided on this topic.. but honestly, if set up properly using TLS and such, API keys are absolutely fine for this use case. It is true that OAuth 2 brings a lot to the table, but it's something that can and should be added later on. If security is a concern, it's trivial to restrict an API key to only certain endpoints / actions, or to whitelist IPs.
Let's assume you have authenticated by whatever method. It's
probably best if that be valid for the whole customer record, so
something like this:
GET https://api.bitfolk.com/v1/guest
…gives you a list of guests. But is that a list of IDs, or a list of
guest names? Let's say it's a list of ID numbers.
If JSON, there's no reason why you can't return a list containing both the ID and its 'friendly name'. If you can envisage ever needing to change a guest name, then it's probably better to use an ID / UUID and use it as per your example below.
Some interesting reading on the topic:
GET https://api.bitfolk.com/v1/guest/1234/xfer
gives you back JSON for the current and predicted amounts in and out
for the current accounting period as well as the period start and
end times for guest id 1234?
Sounds about right.
This is a big project for someone who has never done it before,
unfortunately.
Web is my thing and I've been doing a lot of this stuff lately, especially React + REST gateways. I know that others have offered but I'm also more than happy to donate a bit of time to Bitfolk if you need a hand (crowdsourced feature?), either advice or code / implementation. Personally I use a node stack (e.g. Express or Restify) which can be super lightweight / simple / quick to set up, and being javascript the code is pretty easy to follow / extend for people who have had any level of experience with js.
Regardless of the stack used, if you could make and document some kind of agnostic raw back-end interface in whatever language you prefer (e.g. a CLI perl script with parameters that dumps the relevant data to STDOUT? or basic perl HTTP interface?) which can easily be mocked. Then it would be easy for contibutors to create and harden an API interface without needing access to any of your systems. Once ready, you can just review / test / deploy on your end.
Message me off list if you're interested :)
Cheers,
Luke