[hma] Design a v2 API

[ThisIsMissEm]

We've had a few back and forths about this, but the general direction that I'd take for a v2 API would be:

• Defined using OpenAPI v3
• Inputs and Outputs should use well-known shapes, leaving variable values to the values of well-known keys (i.e., instead of the hash response being keyed by the hash-type, it's instead an array of objects that have a signal_type and hash keys).
• The output from the hashing API should be pipe-able to the matching API — i.e., you shouldn't need to translate the response into a new shape for the request to the matching API.

Initially I'd probably just suggest we start with hashing and matching APIs, but then later expand to this other APIs such as those for managing content banks and exchanges.

There's probably more things related to this that we've discussed and I'm just forgetting those tonight, so feel free to add other things if you remember them.

[Dcallies]

Just adding some more notes, @ThisIsMissEm let me know if I am getting this right. Also cc @juanmrad

On motivation

In the HMA Discord, we had talked about the big problem with the v1 API being that it's hard to write javascript/typescript for, because the API relies on mappings for a lot of things, which get turned into objects, requiring a lot of .entries() and .map() to manipulate. This is fine for python, but a pain for typescript.

The fix is to avoid all usages of Mapping and instead used fix keys - convert all mappings of Map[str, obj] to List[obj{prev_key: str}].

On Implementation

I experimented with https://luolingchun.github.io/flask-openapi3 in a side project as preparation for attempting this, and I think it's preferable to trying to keep a separate doc in sync.

One downside is that it doesn't play nicely with typing, or at least I couldn't figure out how to. The closest I could get was doing something like

class FooModel(base_model):
  foo: int = ...
  bar: str = ...

@...
def my_cool_method() -> str:
  return FooModel(foo=1, bar="a").json()

[Dcallies]

@turt2live - this is the workstream we are talking about. My recommendation is that we created an unstable version of the API and iterate on it, release it in the current major version once we were happy with flask-openAPI support, and then remove the old versions in the next major release (2.x.x)

[turt2live]

That sounds like a good approach to me. Implementations of the unstable API will be important to evaluate its shape, though those implementations may need to be reminded there's risk in targeting unstable endpoints. Specifically, implementations should consider testing new releases/builds of HMA in staging environments if they do decide to deploy code which solely target the unstable endpoints. Code which can switch between unstable and stable-but-undocumented is less affected, and has implicitly done a risk assessment on using unstable targets :)