Welcome back to the new year! Our technical call is on for the usual time (10:00am US Central) tomorrow (Friday the 7th of January 2022).
This week we’re going to discuss the message codes that I’ve checked into the development branch. To recap, Sandpiper provides a “message” property in its JSON responses. This can contain a message code and message text. Until now, we haven’t defined the codes, having had bigger fish to fry, but it’s time to lay them down.
We’ve settled on codes loosely modeled after the HTTP response codes, in that there are reserved areas for basic kinds of messages. But we needed to be sure these were not confused for HTTP codes — which are three numerals long — and so we settled on a four-digit code instead. There are five areas:
- System – 1xxx – used for lower-level messaging that is independent of work area and relationship
- Authorization – 2xxx – used for communication about login and authentication
- Plan – 3xxx – used to convey information about plan workflow events
- Data – 4xxx – used for communication about data updates
- User – 9xxx – used to convey information that the standard codes cannot address
These codes are all present in the sandpiper_db.sql file and will be merged into the documentation after our technical call, assuming all is well.
We also had some good discussions with Aaron at Opticat about the proper way to handle a partially successful authentication, where the plan supplied in the login payload is not acceptable for some reason (e.g. it’s corrupt, isn’t a plan the server recognizes, or so on). Note that the plan itself can be blank in the login request — this is not that. This is where a plan was supplied but rejected by the respondent. We saw two options, and I have my opinions, but I’ll share them and I’d like to discuss.
- Refuse authentication entirely and issue no token, so the initiator can see a clear error occurred
- Authenticate but only authorize for using the basic plan areas, so the client can poll the plans endpoint and make further decisions
Hope to see you tomorrow!