4

Background

I work for a company that provides installation instructions for solar panels on roofs. We also provide an API where external parties can provide roof input and preferences, and return an installation summary, instruction guide, bill of materials, etc.

The biggest hurdle external parties need to go through is the huge amount of "dynamic" constraints that we have. Just a few examples:

  • If your roof has tiles, you need to specify a roof hook type
  • If you have a product preference for product A, you cannot have a vertical rail orientation
  • If your roof is higher than X meters, you also need to specify which product Y you would like to ensure it is really safe.

Now, imagine a constraintset with ~250 of these dynamic constraints. Where one input leads to another required input, or invalidates some other input, or limits a third input, etc.

We have been putting a lot of these constraints in text (and exposing the whole as a swagger documentation), but this is becoming quite an issue in integrating our api for our partners.

The problem they have is not that they can't figure out what is wrong with the request they have sent to us, because we provide them with a meaningful error. No, rather, the problem is that they have no choice but to present this error to their customer, because they don't know beforehand which options they should gray out or not.

Question

I'm looking for some technique to share these kind of validation constraints to our customers, such that they can implement proper input validation before sending a request.

Step 2 is of course automating this so we can update it to always reflect the latest codebase (since we're still working on it).

TL;DR

How can I properly document (a fairly large amount of) highly dynamic constraints on our api so customers integrating our api can implement proper input validation for their endusers?

4
  • So your customers provide a web UI for their clients, and that UI needs machine-readable meta information from your API about what fields to block, or which fields allow only a certain range when a certain value is entered, correct?
    – Doc Brown
    Oct 7, 2021 at 11:08
  • More or less. The API is indeed intended for B2B. So we (A) are exposing our api to company B, which provides a UI to customer C. Company B wants to build a UI with decent UX, so they want to know which options are required, available, and in which combinations. So it's not a matter of machine readable, but we (A) need a proper documentation method so B knows how to build stuff that _just works_™ for their customer C
    – Yuri
    Oct 7, 2021 at 11:10
  • 2
    ... and as we see again, already the typical trigger-happy downvoters around here who seem not to be able to understand the difference between a well written question like this one and the crap which really deserves an unexplained downvote.
    – Doc Brown
    Oct 7, 2021 at 11:58
  • Thanks doc, I was already wondering what I did wrong :)
    – Yuri
    Oct 7, 2021 at 12:14

2 Answers 2

1

This seems to be the perfect use case for implementing a simple rules engine.

In your case, the rules are just "validation rules". Each rule needs to contain the code for the validation (which may throw an exception when the constraint is violated), as well as the documentation of the specific rule. That would allow you

  • to execute the rules during validation in your application

  • ro create a custom documentation generator tool which extracts the docs from the rule objects and includes them into a summary

In case you are implementing and maintaining the rules in code (and not in some DSL), this can be pretty simple and straightforward to implement. Something along the lines of (using C# like pseudo code):

  class ValidationRule
  {
        public abstract void Execute();   // throws an exception when rule is violated
        public abstract string Description();  
  }

  class RoofTileCheck
  {
       // roof can be null in case only the description is required
       public RoofTileCheck(Roof roof)
       {
           this.roof=roof;
       }
       public override void Execute()
       {
           if(roof.HasTiles && roof.Hooktype==Hooktype.None)
                throw new ValidationException($"Roof {roof.ID} has tiles but no hook type");
       }
       public override string Description()
       {
            return "If your roof has tiles, you need to specify a roof hook type";
       }
  }

If all of your 250 rules need different code, this would end up in 250 different classes, but I guess in reality there will probably fewer of them, since some of them can probably be implemented using the same class, just with different constructor parameters.

Finally, you need a factory for instantiating the rule objects for your main application's rule execution loop, and another one for your documentation generator. Maybe it is the same factory if you have a 1:1 correspondence between the specific rules in your application and the docs, and a different one if some rules will only be required as some representatives in the docs.

Of course, this is just a rough guideline and you may need to flesh out a lot of details here, but I gues you got the idea.

2
  • Hi Doc, Thank you for your well written response! And you are spot on. Basically, we have our own basic rule engine. And what I am looking for is how we can properly document these validations for our users. I was wondering if there are some common patterns, complex examples, etc. which may guide us in this.
    – Yuri
    Oct 7, 2021 at 12:13
  • 1
    @Yuri: the architectural pattern here is simply known as Reflection - make your rules include their meta information or descriptions so you can write a tool which extracts them automatically. There are tons of complex examples for this "outside in the wild", almost any kind of documentation generation tool for code works somehow like this. Still you have to tailor these ideas to you specific use case, and if you already have your own rule engine, you should use that as a basis.
    – Doc Brown
    Oct 7, 2021 at 12:18
0

I don't see why this documentation has to be a technical thing. Presumably your constraints are based upon some building standard, or an interpretation of one, which has been conveyed to you in a way you have been able to build the API. Surely those documents are pretty close to what you need to give your clients as you've built your API on that basis. In terms of specific formal documentation techniques, you could look at BNF. Pretty old school but if I understand you correctly it might work for you. If you have a robust parser for your API input you might even be able to generate docco from that. If you have any sort of data driven rules engine you use to validate your API inputs against, you might be able to eject documentation on those rules as well as enforce them.

Another approach is to have a "try" version of your API which will somehow hook into the rules and provide a feedback response as to what constraints apply to further parameters/values (e.g. required or optional or n/a) given a particular state of data entry so far. The client can drive their UI from that.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.