Actions

[kinlane]

Wanted to have a place to have conversations about how we reflect actions in the API design. Right now the API design is very CRUD, and there really aren't any actions beyond just verbs.

I'd like to have an ongoing discussion around how we reflect more advanced actions in the API design, allowing for more actions to be taken after we get more feedback from the community.

[NeilMcKLogic]

I know that Kate (where's her Github handle in autosuggest gone?) had some superb use cases that would help us flesh out much more nuanced components of both the API and data structure specifications. We should at a minimum revive those for this convo.

[greggish]

cc @klambacher

[klambacher]

I'm swamped this week but will set myself a reminder to come back to this next week. I think perhaps an actual document talking about use cases and their usual requirements would help (I've got some past real-world asks to back it up). Sorry for being out of the loop - illness + deadlines are a bad combo!

[greggish]

We have begun outlining user personas and their associated stories in the project charter document, though it makes sense for us to expand those into their own document. Would welcome suggestions and contributions here.

[kinlane]

Thanks for this thread. Making actions intuitive and meaningful is important -- we have time on this one, so whenever we can start building a list of real world actions against organizations, locations, services and others would go long way to help me think through the evolution of spec.

[klambacher]

Ok, it's taken me a while but here I am back to this thread ;)

I mentioned in a previous call that our major real-world use cases (which can overlap) include:

1. One-time exporters, often for reporting or basic inventory project of a category of services by 3rd parties. Tends to favour simplified, flat data, doesn't care much about updates or maintenance, doesn't contribute to the data source or add permanent data extensions. "I just want a CSV with these fields for this type of record".

2. Data-extenders want the information, but find it inadequate for their needs. They want to add additional fields, sometimes with added complexity or domain-specific information, and most particularly extra categorization. Sometimes they want to extend the resource database because it's missing "a few resources we need". Most data-extenders - well more than half - don't have an existing system (or at least one they like), or dedicated person resources in the organization to maintain information. In our system, these folks often work within the system and add on to information shared with them by others. "You have almost everything I need, could we add a few new fields and records?"

3. Brand-makers want to look like the information belongs to them. They want to select information useful to their staff or clients, and they want to fit in with their brand and make it look like they have some ownership of the information (actually having ownership generally doesn't matter!). They can be "Data-extenders" too, but most often what they care about is having the information fit in with their website and services and rarely take an active role in modifying or adding to the data. Sometimes they use integration into their own system as a solution, but that isn't generally an important part; it is about making their clients (or possibly staff) see the data as part of their internal offerings/services. Pull-and-display API-driven websites (no data storage or search logic of their own), or simple in-system branding are often the solution of choice. Search parameters matter in an API-driven option, since this client is entirely dependent on the API for all functionality including search logic, and only handles display. "Can I have this look like my website?"

4. Integraters want to combine information into existing systems or datasets. They are committed to the system they use, and may have a substantial existing data set that is outside of the collection policy of the target dataset they want to integrate. They care deeply about ongoing maintenance and updates of the information and often move large quantities of information frequently. Over time, this can sometimes become a bi-directional sharing relationship if the initial integration is successful. Efficient ways to determine changes and keep data in sync between systems is what matters, and search features are generally irrelevant beyond the ability to query changes and do sanity checks. Efficient movement of data in bulk is important and pull-and-display APIs often require too many requests to collect information. "I'd like to integrate your information into our existing database, on this schedule"

[greggish]

@klambacher super interesting. I'd like to hold this framework alongside our initial framework for Use Types and Use Cases.

Is it possible that there is overlap between these sets of types? I could easily see someone being 2, 3, and 4 simultaneously.

[klambacher]

@greggish yes, absolutely there is overlap, but each can be quite independent too.

Obviously this is a very different approach to the use cases from what you have in your document, and I think it's good to recognize these roles through both filters. From my end (as the person who gets contacted when someone wants to start doing a data exchange, integration, portal, etc) people always come with very strong positions reflecting one or more of the 4 above, and that's what forms the basis for me recommending what they need. To meet all of these needs we've today got quite the puzzle of manual and automated import/exports formats, simplified and full-display APIs, CMS plugins, etc.. I would think of it as a great success if we could identify how each of the types of real-world projects we have today might accomplish their goals with the API.

[greggish]

Ok. I've added these to our documentation, and will open the issue for our consideration on the call. We'll put some time into discussing this.