2

I’m integrating with the Ajax Enterprise API which exposes an AWS SQS feed for device events and notifications. The API documentation is here: Ajax Enterprise API Docs.

Each SQS message supplies an event code, which is then used to look up the corresponding log message. This is supplied with placeholders, which you then substitute with other data in the SQS message.

Example: "M_01_20": "%3$s: open, %1$s in %2$s" -> "MyHub: open, MyDetector in MyRoom"

In an ideal world the feed would just supply the fully formed log message, but it doesn't. I don't know why.

As it stands I’ve run into multiple issues that make reliable integration very difficult:

  1. Undocumented placeholders: Event messages returned by the feed contain placeholders like %1$s, %2$s, %3$s, %4$s, %5$s. There is no clear definition of which keys in the SQS JSON correspond to %4$s and %5$s. Based on what I have been told by email, %4$s seems overloaded and can refer to different things depending on the event type (user email, device name, hub line number, etc.).
  2. Silent/unversioned changes: Placeholder assignments have changed without notice. For example, an event that previously used %5$s to refer to a user now uses %4$s. New event codes can be added seemingly at any time, which unless I have hardcoded the definition for, cannot be handled.
  3. Lack of data model definition: There’s no formal schema for the SQS JSON. The one listed is out of date and incomplete. For example, there's now an eventTypeV2 field - never explained anywhere, and which broke my integration. There's an additionalData object and its contents changes for different event codes, which is never detailed.
  4. Documentation lag: The official docs are maintained by the marketing team, not technical, and are not updated in real-time with the live system. This makes it impossible to rely on them for critical security notifications. I received a spreadsheet of separate event codes, different to the online list, that I am told is current.
  5. Lack of response: When I've raised these issues, they've either not been answered, or treated as not important.

Overall, I’m left thinking that the SQS feed is highly unreliable for an enterprise integration. I do not have control over the security system used: it is the client's choice for an app. I have informed them of my concerns.

Any thoughts or recommended strategies would be appreciated.

Improve this question
4
  • What's an SQS feed? Sorry, I'm not familiar with the term. Commented Aug 22 at 16:53
  • 1
    How would a full-formed message be localized? Commented Aug 22 at 17:23
  • @GregBurghardt It's an Amazon Simple Queue Service: docs.aws.amazon.com/AWSSimpleQueueService/latest/… Commented Aug 22 at 18:43
  • @Basilevs That's a good point, but at the moment the brittleness of the current setup seems to outweigh any benefit gained from localisation. Commented Aug 22 at 18:44

2 Answers 2

Reset to default
4

The thing with API's is that they are designed for computer use, not human.

From the computers viewpoint the string error message is useless. You have all the info you need in the event code and fields to construct your own message in various languages etc.

What I think is happening here is that the devs have just exposed the raw log messages. $1, $2 etc are just the parameters sent when calling the logger in the order they are in the code. ie

console.log(“%3$s: open, %1$s in %2$s”, "detector name", "room name", "device type");

If the dev is copying and pasting, you might find that the order of the parameters is generally the same, but there no reason some device code else where might have

console.log(“%1$s: open, %2$s in %3$s”, "device type", "detector name", "room name");

My advice would be to ignore the message template entirely. Use the event code to look up the intent of the message and construct your own plain english version of it as required.

Improve this answer
3
  • Good advice, though a bit difficult to manually account for 1,200+ event codes. Commented Aug 25 at 9:36
  • just looking through the list.. even more confusing, what is device type 21? I guess the thing is each device has its own list of events. Commented Aug 25 at 21:07
  • This is the fundamental problem. Things are added but aren't documented anywhere, and nothing is versioned so they're just thrown live without warning. Look through the event codes list and there are lots of unexplained devices. Commented Aug 26 at 20:12
2

When I encounter poor documentation I generally go to the source code, initial design documentation, blame.

If I am not banned from the organization or repository I notify the maintainers about the issue with the documentation.

If I am banned from the organization or repository I try to reach out to developers in the field to fix the documentation with a roadmap I provide.

During the process I generally write a gist on GitHub explaining what is undocumented, what I discovered in source code comments, blame, etc., and update the gist. That provides some form of documentation for myself and other developers that might find themselves in the same situation.

There's a few errors or omissions on MDN that I have brought to the attention of stakeholders and developers. Some have current PR's to fix the errors or omissions, some just languish right now as simply wrong on MDN.

Sometimes specifications themselves can be ambiguous, leaving room for "host implementations" to do or not do whatever they want in a given scenario; for example dynamic import() in ECMA-262.

Sometimes implementers ignore specifications and do what they want; e.g., in the case of WHATWG Fetch and full-duplex streaming.

What I would do is start the documentation process in a gist based on what you find in tests for the specific parameters and results you get.

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.