json-apisuitecrm

JsonAPI SuiteCRM pulling back multiple records


I am currently doing a suitecrm implementation and my client has the requirement of pulling back all prospects that belong to a specific prospect list programmatically.

In suitecrm getting a list of prospects is easy

GET: /module/api/v8/Prospects

Also getting the prospect lists are simple

GET: /module/api/v8/Prospect_Lists

However, in the JSON API Spec, the relationship exists by calling an API to provide you with a list of related objects, for example GET: /Api/V8/module/ProspectLists/a8f704d4-c25b-53e6-a7fc-6005b93835cd/relationships/prospects Returns an array of prospect Id's that are related to the Prospect_List. Example response:

{
  {
  "data": [
        {
            "type": "Prospect",
            "id": "9c3d7edf-9679-eff3-9ff0-60197fe7af68",
            "links": {
                "self": "V8/module/Prospect/9c3d7edf-9679-eff3-9ff0-60197fe7af68"
            }
        },
        {
            "type": "Prospect",
            "id": "d4ab2b49-c95d-9a64-4770-601c2b658adf",
            "links": {
                "self": "V8/module/Prospect/d4ab2b49-c95d-9a64-4770-601c2b658adf"
            }
        },
           ]

}

My question is, with the JSON Api (Specifically suitecrm) is it possible to pull back all the related records (the full records, not just the ID's) in one shot rather than loop through the array and do get requests one by one?

I did test using the filter parameter which does not seem to do the trick and scares me anyway because of the variable length nature of the returned data.


Solution

  • You question contains of two parts:

    1. Linking related resources in JSON:API specification
    2. Implementation of JSON:API specification in SuiteCRM

    Let me answer them one after the other.

    Linking related resources in JSON:API specification

    The JSON:API specification defines to links for relationships:

    1. Relationship Links
    2. Related Resource Links

    They may be included in the links member of a relationship object. The self key provides the Relationship Link. The related key provides the Related Resource Link.

    A Relationship Link is defined as "a link for the relationship itself. This link allows the client to directly manipulate the relationship. [...] When fetched successfully, this link returns the linkage for the related resources as its primary data." (Source)

    Resource Linkage mentioned in the definition is the Resource Identifier Objects of the related resource (has-one relationship) or resources (has-many relationship). A Resource Identifier Object is the unique combination of type and id of a specific resource, which identifies it.

    A Related Resource Link "provides access to resource objects linked in a relationship. When fetched, the related resource object(s) are returned as the response’s primary data."

    To summarize for GET operations:

    1. Relationship Links provides type and id of related resource or resources.
    2. Related Resource Links provides the full resource objects of the related resources.

    It's up to the implementation if both, a Relationship Link and a Related Resource Link, is provided for a specific relationship, only one of them or none.

    Implementation of JSON:API specification in SuiteCRM

    I don't have experience with SuiteCRM API myself. All information provided are based on public documentation Suite CRM API V8 and the information provided in your question.

    SuiteCRM provides an example response of a request to get a single resource:

    {
        "data": {
            "type": "Account",
            "id": "11a71596-83e7-624d-c792-5ab9006dd493",
            "attributes": {
                "name": "White Cross Co",
                "account_type": "Customer"
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                        "related": "/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493/relationships/aos_contracts"
                    }
                }
            }
        }
    }
    

    The resource object for the Account with ID 11a71596-83e7-624d-c792-5ab9006dd493 includes a Related Resource Link for the AOS_Contracts relationship. It is /V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493/relationships/aos_contracts.

    The response you included would not be what I would expect from a Related Resource Link. It does not include any fields of the Prospect resources. It looks like Resource Identifier Objects with additional self link.

    I don't think this is wrong strictly speaking. The JSON:API specification allows the server to include only a subset of all fields in the response by default. That subset may be different depending on the endpoint. But it's at least very uncommon.

    In that case you should be able to request inclusion of specific fields using Sparse Fieldsets feature. I don't know the fields of Prospect resource in SuiteCRM. But assuming it has a name attribute, you could request to include it (and only it) with adding these query parameter to the Related Resource Link: ?fields[Prospect]=name.