You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Background : we want to include limit/depth/pagination in CPS-Core query APIs where output size is large. it will allow user to limit query outputs.

It was discussed on 11th Nov 2022 in weekly meeting to use 'depth' parameter to limit large outputs.


Implementation : 


'depth' query parameter added in below URLsNotesDecision
URL: http://<IP:PORT>/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/node?xpath=/&descendants={all | none | number}

descendants is optional query parameter with default value of "all". possible values of descendants is as below :

  1.  all : to get all descendants 
  2.  none: don't include descendants
  3.  number : positive number 1 to n, to query nodes till nth descendant 
  1. we need to support different version for this query API for backward compatibility 
URL: http://<IP:PORT>/v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/query?cps-path=/&descendants={all | none | number}

descendants is optional query parameter with default value of "all". possible values of descendants is as below :

  1.  all : to get all descendants 
  2.  none: don't include descendants
  3.  number : positive number 1 to n, to query nodes till nth descendant 
  1. we need to support different version for this query API for backward compatibility 



Implementations: 

changes files changes/notesDecision
cpsData.yml
nodeByDataspaceAndAnchor:
  get:
    ...
      - $ref: 'components.yml#/components/parameters/descendantsInQuery'
...

cpsQuery.yml
nodesByDataspaceAndAnchorAndCpsPath:
  get:
    ...
      - $ref: 'components.yml#/components/parameters/descendantsInQuery'
...

components.yml
descendantsInQuery:
  name: descendants
  in: query
  description: descendants parameter to limit descendants. use "all", "none" or number
  required: false
  schema:
    type: string
    default: all
    example: 3
    pattern: <use pattern to validate accepted values for descendants>

DataRestController.java
@Override
public ResponseEntity<Object> getNodeByDataspaceAndAnchor(final String dataspaceName, final String anchorName,
    final String xpath, final String descendants) {
    final FetchDescendantsOption fetchDescendantsOption = Boolean.TRUE.equals(includeDescendants)
        ? new FetchDescendantsOption(depth) : FetchDescendantsOption.OMIT_DESCENDANTS;
    final DataNode dataNode = cpsDataService.getDataNode(dataspaceName, anchorName, xpath,
        fetchDescendantsOption, depth);
    final String prefix = prefixResolver.getPrefix(dataspaceName, anchorName, xpath);
    return new ResponseEntity<>(DataMapUtils.toDataMapWithIdentifier(dataNode, prefix), HttpStatus.OK);
}

private FetchDescendantsOption getFetchDescendantsOption(String descendants) {
    if("all".equals(descendants)){
       return FetchDescendantsOption.INCLUDE_ALL_DESCENDANTS; 
    } else if("none".equals(descendants)){
       return FetchDescendantsOption.OMIT_DESCENDANTS;
    } else {
        return new FetchDescendantsOption(Integer.valueOf(descendants));
    }
}

  • No labels