From 53807eb36d72ff5639acb85f3f15d914af6830b6 Mon Sep 17 00:00:00 2001 From: "Barry M. Caceres" Date: Fri, 19 Mar 2021 14:09:26 -0700 Subject: [PATCH 1/5] Fixed the type for progressPeriod query parameter --- senzing-rest-api.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/senzing-rest-api.yaml b/senzing-rest-api.yaml index 4c4a4ac..cdaf577 100644 --- a/senzing-rest-api.yaml +++ b/senzing-rest-api.yaml @@ -3477,7 +3477,8 @@ components: is not producing an SSE response (i.e.: `text/event-stream` media type was not requested via the `Accept` header). schema: - type: string + type: integer + format: int64 default: 3000 responses: ServerError: From de7f78f8e4614eff22c9247f4dcfa0df8120678e Mon Sep 17 00:00:00 2001 From: "Barry M. Caceres" Date: Tue, 23 Mar 2021 11:20:17 -0700 Subject: [PATCH 2/5] Added nativeApiBuildVersion to SzVersionInfo and SzMeta --- senzing-rest-api.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/senzing-rest-api.yaml b/senzing-rest-api.yaml index cdaf577..c1ccc8e 100644 --- a/senzing-rest-api.yaml +++ b/senzing-rest-api.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: title: Senzing REST API - version: "2.4.0" + version: "2.5.0" description: >- This is the Senzing REST API. It describes the REST interface to Senzing API functions available via REST. It leverages the @@ -3521,6 +3521,8 @@ components: type: string nativeApiVersion: type: string + nativeApiBuildVersion: + type: string nativeApiBuildNumber: type: string nativeApiBuildDate: @@ -4255,6 +4257,10 @@ components: type: string description: >- The version for the underlying runtime native Senzing API. + nativeApiBuildVersion: + type: string + description: >- + The build version for the underlying runtime native Senzing API. nativeApiBuildNumber: type: string description: >- From cd4642b4a958a1c1bcdcdf8e9f905be9a9e708ea Mon Sep 17 00:00:00 2001 From: "Barry M. Caceres" Date: Tue, 23 Mar 2021 21:10:52 -0700 Subject: [PATCH 3/5] Added "POST /search-entities" endpoint --- senzing-rest-api.yaml | 184 +++++++++++++++++++++++++++++++----------- 1 file changed, 135 insertions(+), 49 deletions(-) diff --git a/senzing-rest-api.yaml b/senzing-rest-api.yaml index c1ccc8e..58be00f 100644 --- a/senzing-rest-api.yaml +++ b/senzing-rest-api.yaml @@ -1430,7 +1430,7 @@ paths: summary: >- Search for entities that would match or relate to the provided entity features. - operationId: searchByAttributes + operationId: searchEntitiesByGet parameters: - name: attrs description: | @@ -1477,28 +1477,11 @@ paths: summary: Not specified value: ssnExample: - summary: Social security number - value: >- - { - "SSN_NUMBER": "111-22-3333" - } + $ref: '#/components/examples/ssnSearchExample' nameAndBirthDateExample: - summary: Name and date of birth - value: >- - { - "NAME_FULL": "JANE SMITH", - "DATE_OF_BIRTH": "03-SEP-1987" - } + $ref: '#/components/examples/nameAndBirthDateSearchExample' nameAndAddressExample: - summary: Name and address - value: >- - { - "NAME_FULL": "JANE SMITH", - "ADDR_LINE1": "653 STATE ROUTE 7", - "ADDR_CITY": "FRESNO", - "ADDR_STATE": "CA", - "ADDR_POSTAL_CODE": "55073-1234" - } + $ref: '#/components/examples/nameAndAddressSearchExample' - name: attr description: >- Either the `attrs` or `attr` parameter is required, **however** if @@ -1547,41 +1530,91 @@ paths: "WORK_ADDR_CITY:Pasadena", "WORK_ADDR_STATE:CA" ] - - name: includeOnly + - $ref: '#/components/parameters/includeOnlyQueryParam' + - $ref: '#/components/parameters/featureModeQueryParam' + - $ref: '#/components/parameters/withFeatureStatsQueryParam' + - $ref: '#/components/parameters/withInternalFeaturesQueryParam' + - $ref: '#/components/parameters/forceMinimalQueryParam' + - $ref: '#/components/parameters/withRelationshipsQueryParam' + - $ref: '#/components/parameters/withRawQueryParam' + responses: + '200': + description: Successful response + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzAttributeSearchResponse' + application/json: + schema: + $ref: '#/components/schemas/SzAttributeSearchResponse' + default: + schema: + $ref: '#/components/schemas/SzAttributeSearchResponse' + '400': description: >- - Optional parameter that can be specified zero or more times to - indicate which `SzAttributeSearchResultType`'s should be included - in the search results. If not specified then all match types are - included. *NOTE*: This parameter is ignored unless the underlying - native Senzing API is version 2.4.1 or later. - in: query - required: false - schema: - type: array - items: - $ref: '#/components/schemas/SzAttributeSearchResultType' - examples: - notSpecifiedExample: - summary: Not specified - include all search results - value: - includeOnlyMatches: - summary: Only include matches - value: [ "MATCH" ] - includeOnlyMatchesAndPossibleMatches: - summary: Only include matches and possible matches. - value: [ "MATCH", "POSSIBLE_MATCH" ] - includeAllButNameOnlyMatches: - summary: Include all but name-only matches. - value: [ "MATCH", "POSSIBLE_MATCH", "POSSIBLE_RELATION" ] - includeOnlyNameOnlyMatches: - summary: Only include name-only matches. - value: [ "NAME_ONLY_MATCH" ] + If the specified attrs parameter is missing or is not formatted + properly. + content: + application/json; charset=UTF-8: + schema: + $ref: '#/components/schemas/SzErrorResponse' + application/json: + schema: + $ref: '#/components/schemas/SzErrorResponse' + default: + schema: + $ref: '#/components/schemas/SzErrorResponse' + '500': + $ref: '#/components/responses/ServerError' + /search-entities: + post: + tags: + - Entity Data + summary: >- + Search for entities that would match or relate to the provided + entity features. This is similar to `GET /entities` except it requires + the caller to specify the search criteria as JSON in the request body. + operationId: searchEntitiesByPost + parameters: + - $ref: '#/components/parameters/includeOnlyQueryParam' - $ref: '#/components/parameters/featureModeQueryParam' - $ref: '#/components/parameters/withFeatureStatsQueryParam' - $ref: '#/components/parameters/withInternalFeaturesQueryParam' - $ref: '#/components/parameters/forceMinimalQueryParam' - $ref: '#/components/parameters/withRelationshipsQueryParam' - $ref: '#/components/parameters/withRawQueryParam' + requestBody: + description: >- + The JSON record describing the entity attributes in the same format as + how an entity record is loaded The format of the JSON is described by + the [Senzing Generic Entity Specification](https://senzing.zendesk.com/hc/en-us/articles/231925448-Generic-Entity-Specification). + The specified attributes are treated as a hypothetical record being + loaded, and the result is anything that would have matched or related + to it. + required: true + content: + application/json; charset=UTF-8: + schema: + type: object + additionalProperties: {} + examples: + ssnExample: + $ref: '#/components/examples/ssnSearchExample' + nameAndBirthDateExample: + $ref: '#/components/examples/nameAndBirthDateSearchExample' + nameAndAddressExample: + $ref: '#/components/examples/nameAndAddressSearchExample' + application/json: + schema: + type: object + additionalProperties: {} + examples: + ssnExample: + $ref: '#/components/examples/ssnSearchExample' + nameAndBirthDateExample: + $ref: '#/components/examples/nameAndBirthDateSearchExample' + nameAndAddressExample: + $ref: '#/components/examples/nameAndAddressSearchExample' responses: '200': description: Successful response @@ -3119,6 +3152,29 @@ components: multipleEntitiesByMixedRecordIdArrayExample: summary: Multiple entities by mixed-encoded record ID value: '[":CUSTOMERS:GHI789",{"src":"EMPLOYEES","id":"JKL321"}]' + ssnSearchExample: + summary: Social security number + value: >- + { + "SSN_NUMBER": "111-22-3333" + } + nameAndBirthDateSeachExample: + summary: Name and date of birth + value: >- + { + "NAME_FULL": "JANE SMITH", + "DATE_OF_BIRTH": "03-SEP-1987" + } + nameAndAddressSearchExample: + summary: Name and address + value: >- + { + "NAME_FULL": "JANE SMITH", + "ADDR_LINE1": "653 STATE ROUTE 7", + "ADDR_CITY": "FRESNO", + "ADDR_STATE": "CA", + "ADDR_POSTAL_CODE": "55073-1234" + } bulkDataCSVExample: summary: Bulk records in CSV format value: >- @@ -3378,6 +3434,36 @@ components: schema: type: boolean default: false + includeOnlyQueryParam: + in: query + name: includeOnly + description: >- + Optional parameter that can be specified zero or more times to + indicate which `SzAttributeSearchResultType`'s should be included + in the search results. If not specified then all match types are + included. *NOTE*: This parameter is ignored unless the underlying + native Senzing API is version 2.4.1 or later. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/SzAttributeSearchResultType' + examples: + notSpecifiedExample: + summary: Not specified - include all search results + value: + includeOnlyMatches: + summary: Only include matches + value: [ "MATCH" ] + includeOnlyMatchesAndPossibleMatches: + summary: Only include matches and possible matches. + value: [ "MATCH", "POSSIBLE_MATCH" ] + includeAllButNameOnlyMatches: + summary: Include all but name-only matches. + value: [ "MATCH", "POSSIBLE_MATCH", "POSSIBLE_RELATION" ] + includeOnlyNameOnlyMatches: + summary: Only include name-only matches. + value: [ "NAME_ONLY_MATCH" ] withInfoQueryParam: in: query name: withInfo From 5e01826c09ced27f81c20ade378c4c138f3ed894 Mon Sep 17 00:00:00 2001 From: "Barry M. Caceres" Date: Tue, 23 Mar 2021 21:17:27 -0700 Subject: [PATCH 4/5] Updated CHANGELOG.md --- CHANGELOG.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f198da3..5a1b162 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), [markdownlint](https://dlaa.me/markdownlint/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.5.0] - 2021-03-24 + +### Changed in 2.5.0 + +- Added `nativeApiBuildVersion` to meta (`SzMeta`) +- Added `nativeApiBuildVersion` to `SzVersionInfo` +- Added `POST /search-entities` endpoint to provide a `POST` variant of + `GET /entities` that uses the request body instead of the `attr` and `attrs` + query parameters +- Fixed type of `progressPeriod` parameter ## [2.4.0] - 2021-03-11 From cd953656f0668436ce11f906da80a02d5da74696 Mon Sep 17 00:00:00 2001 From: "Barry M. Caceres" Date: Tue, 23 Mar 2021 21:33:41 -0700 Subject: [PATCH 5/5] Fixed typo in example reference. Added path component to base URL at the start of the file --- senzing-rest-api.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/senzing-rest-api.yaml b/senzing-rest-api.yaml index 58be00f..325bc45 100644 --- a/senzing-rest-api.yaml +++ b/senzing-rest-api.yaml @@ -23,7 +23,7 @@ info: servers: - url: http://localhost:8250 - - url: '{protocol}://{host}:{port}' + - url: '{protocol}://{host}:{port}{path}' variables: protocol: enum: @@ -34,6 +34,8 @@ servers: default: localhost port: default: '8250' + path: + default: '/' paths: /heartbeat: @@ -3158,7 +3160,7 @@ components: { "SSN_NUMBER": "111-22-3333" } - nameAndBirthDateSeachExample: + nameAndBirthDateSearchExample: summary: Name and date of birth value: >- {