Skip to end of metadata
Go to start of metadata

Design Principles

  • TDD - tests come first; writing the tests will inform design decisions.
  • Clean - leave all the legacy cruft in v3 and start with a clean slate.
  • Consistent - uniformity between all entities as much as possible, minimize oddities.
  • Strict - ditch the aliases, unique names, camelCase conversions, and alternate syntaxes. Params will only be accepted in one format.
  • OOP - use classes in the \Civi namespace - minimize boilerplate via class inheritance/traits.
  • Discoverable - params are self-documenting through fluent style and api reflection; no undocumented params
  • Doable - prioritize new features based on impact and keep scope proportionate to developer capacity.

Input

$params array will be organized into categories, expanding on the "options" convention in v3:

Output

The php binding returns an arrayObject. This gives immediate access to the results, plus allows returning additional properties.

We can do the something very similar in javascript thanks to js arrays also being objects:

 

Feature Wishlist

  • Get Action
    • OR as well as AND in select queries.
    • Ability to add a field to a query more than once e.g. "sort_name LIKE 'bob' OR sort_name LIKE 'robert'".
    • Joins across all FKs and pseudo FKs.
  • Delete Action
    • Delete multiple items at once.
    • Search by any field, not just ID
  • Error Handling
    • Ability to simulate an api call
    • Report on all errors, not just the first one to be thrown

Contributing

Work is in-progress on the org.civicrm.api4 extension.

To contribute, you can submit a pull-request to civicrm/api4 or request push-access from Coleman.

The JIRA issue number is CRM-17867

Labels
  • None
  1. Feb 17, 2016

    1. If no select is included the default should be just id rather than all fields to be more performant; I think Eileen mentioned this in a conversation.

     

    2. As a result there may be a need to have one method that returns all available fields on the entity, and potentially a different one for the actual fields in the entity.

  2. Jan 12, 2017

    One of the things that turned out to be extremely helpful in my app was the ability to represent a list definition as a JSON string. This means that writing code to allow each user to save their list on their dashboard (or onto the dashboard of their teams) was quite trivial.

    Also once I had a syntax for handling intersection I was able to handle permissions as simply another set in the intersection list and this was added as needed.

  3. Jan 12, 2017

    I also encourage the handling of NOT (as well as OR and AND)

    The rationale is that NOT is a frequent requirement for many deeper calls ("not in group", "not tagged", "did not attend event", "has not donated")

    By making NOT part of the overall query framework it means that each individual API no longer needs to handle it.

  4. Jan 12, 2017

    from what I can glean the search builder is independent of the API?

    Having the search builder as basically a fancy API call constructor means that the API gets some more features it would otherwise miss.

    It also mean that extension authors get a much more powerful toolbox...

  5. Jan 12, 2017

    Wish list for gets:

    + cachable

  6. Jan 12, 2017

    wishlist for updates:

    + able to update one or more entities on a single call


Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.