Search APIs

The Search APIs have implemented the G2P Connect Registry Core APIs specification. These APIs are designed to offer comprehensive searching capabilities across individual and group registries. It utilizes advanced query options for precise results. The API facilitates querying across all Social Registry (SR) registrants. It leverages GraphQL to handle complex queries efficiently. It retrieves only the requisite data for a specific query.

Authentication

OpenG2P Social Registry Search API is secured by OAuth 2.0. It uses Client Credentials Grant Type, i.e., Client ID and Secret to allow the end-user to access the Social Registry database.

Key request parameters - authorization

Once you receive the Client ID and Secret, the next step is to call OAuth 2.0 endpoint to authenticate.

The key parameters are:

Name	Value
Method	POST
Authorization type	Bearer Token
Auth URI	http://keycloak.keycloak/realms/openg2p/protocol/openid-connect/token

Body request parameters

Name	Value
client_id	<client_id>
client_secret	<client_secret>
grant_type	client_credentials

Sample cURL request

curl --location 'https://keycloak.keycloak/realms/openg2p/protocol/openid-connect/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'client_id=<client_id>'
--data-urlencode 'client_secret=<client_secret>'
--data-urlencode 'grant_type=client_credentials'

On receiving the request, OpenG2P authorization system validates the parameters in the request. If the parameters are valid, it generates your access token and returns it in the response.

Sample response

{
    "access_token": "",
    "expires_in": 0,
    "refresh_expires_in": 0,
    "token_type": "",
    "not-before-policy": 0,
    "scope": ""
}

HTTP status code

HTTP Code	Description
200	The API call is successful.
400	Bad Request. The request is invalid, usually due to missing or incorrect parameters.
401	Unauthorized. Authentication failed due to an invalid Client ID or Secret.

Query type

The search api utilizes GraphQL query parameters. The query parameter enhances the search efficiency and eases the data retrieval. You must consider the following parameters when crafting a GraphQL query parameters.

• Query Filters: When sending a request, you can define specific criteria to filter the data. You can filter based on various parameters such as age, location, or status of the registrants in the SR.

• Fields Selection: GraphQL allows you to specify the fields you need to receive in response based on your query. This means you can tailor the response to include only the relevant data that fulfills your needs. This makes the API response more lightweight and accurate.

• Pagination Parameters: For queries that return large data, it is mandatory to break into several pages through pagination. GraphQL uses the query parameter to set the limit and offset to return the number of records per page.

• Sort Order: You can specify the order to organize the data that you need to receive in response. You can sort ascending or descending based on a specific field.

Sample GraphQL query

{
  getregistrants(address: "New York", sort: "id DESC", limit: 20, offset: 20) {
    name,
    age,
    gender,
    address
  }
}

For example, the query returns the name, age, gender, and address of next page 20 registrants who are residing in New York, and the ids are sorted in descending order.

API specification

The Search APIs are available in Stoplight at the following link.

openg2p-social-registry-search-apis