Package org.odpi.openmetadata.accessservices.datamanager.api

Interface APIManagerInterface

All Known Implementing Classes:

APIManagerClient

public interface APIManagerInterface

APIManagerInterface defines the client side interface for the Data Manager OMAS that is relevant for API assets that provide call-based services. It provides the ability to define and maintain the metadata about an API and the APIOperations that define the operations and parameters of the API.

Method Summary

Modifier and Type	Method	Description
String	createAPI(String userId, String apiManagerGUID, String apiManagerName, boolean apiManagerIsHome, String endpointGUID, APIProperties apiProperties)	Create a new metadata element to represent an API.
String	createAPIFromTemplate(String userId, String apiManagerGUID, String apiManagerName, boolean apiManagerIsHome, String endpointGUID, String templateGUID, TemplateProperties templateProperties)	Create a new metadata element to represent an API using an existing metadata element as a template.
String	createAPIOperation(String userId, String apiManagerGUID, String apiManagerName, String apiGUID, APIOperationProperties properties)	Create a new metadata element to represent an API Operation.
String	createAPIOperationFromTemplate(String userId, String apiManagerGUID, String apiManagerName, String templateGUID, String apiGUID, TemplateProperties templateProperties)	Create a new metadata element to represent a an API Operation using an existing API Operation as a template.
String	createAPIParameterList(String userId, String apiManagerGUID, String apiManagerName, String apiOperationGUID, APIParameterListType parameterListType, APIParameterListProperties properties)	Create a new metadata element to represent an API Operation's Parameter list.
String	createAPIParameterListFromTemplate(String userId, String apiManagerGUID, String apiManagerName, String templateGUID, String apiOperationGUID, APIParameterListType parameterListType, TemplateProperties templateProperties)	Create a new metadata element to represent a an API Parameter List using an existing API Parameter List as a template.
List<APIOperationElement>	findAPIOperations(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of API Operations metadata elements that contain the search string.
List<APIParameterListElement>	findAPIParameterLists(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of API Parameter List metadata elements that contain the search string.
List<APIElement>	findAPIs(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of API metadata elements that contain the search string.
APIElement	getAPIByGUID(String userId, String guid)	Retrieve the API metadata element with the supplied unique identifier.
APIOperationElement	getAPIOperationByGUID(String userId, String guid)	Retrieve the API Operation metadata element with the supplied unique identifier.
List<APIOperationElement>	getAPIOperationsByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of API Operations metadata elements with a matching qualified or display name.
APIParameterListElement	getAPIParameterListByGUID(String userId, String guid)	Retrieve the API Parameter List metadata element with the supplied unique identifier.
List<APIParameterListElement>	getAPIParameterListsByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of API Parameter List metadata elements with a matching qualified or display name.
List<APIElement>	getAPIsByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of API metadata elements with a matching qualified or display name.
List<APIElement>	getAPIsForAPIManager(String userId, String apiManagerGUID, String apiManagerName, int startFrom, int pageSize)	Retrieve the list of APIs created by this caller.
List<APIElement>	getAPIsForEndpoint(String userId, String endpointGUID, int startFrom, int pageSize)	Retrieve the list of APIs connected to the requested endpoint.
List<APIOperationElement>	getOperationsForAPI(String userId, String apiGUID, int startFrom, int pageSize)	Return the list of API Parameter Lists associated with an API Operation.
List<APIParameterListElement>	getParameterListsForAPIOperation(String userId, String apiOperationGUID, int startFrom, int pageSize)	Return the list of API Parameter Lists associated with an API Operation.
void	publishAPI(String userId, String apiGUID)	Update the zones for the API asset so that it becomes visible to consumers.
void	removeAPI(String userId, String apiManagerGUID, String apiManagerName, String apiGUID, String qualifiedName)	Remove the metadata element representing an API.
void	removeAPIOperation(String userId, String apiManagerGUID, String apiManagerName, String apiOperationGUID, String qualifiedName)	Remove an API Operation.
void	removeAPIParameterList(String userId, String apiManagerGUID, String apiManagerName, String apiParameterListGUID, String qualifiedName)	Remove an API Parameter List and all of its parameters.
void	updateAPI(String userId, String apiManagerGUID, String apiManagerName, String apiGUID, boolean isMergeUpdate, APIProperties apiProperties)	Update the metadata element representing an API.
void	updateAPIOperation(String userId, String apiManagerGUID, String apiManagerName, String apiOperationGUID, boolean isMergeUpdate, APIOperationProperties properties)	Update the metadata element representing an API Operation.
void	updateAPIParameterList(String userId, String apiManagerGUID, String apiManagerName, String apiParameterListGUID, boolean isMergeUpdate, APIParameterListProperties properties)	Update the metadata element representing an API ParameterList.
void	withdrawAPI(String userId, String apiGUID)	Update the zones for the API asset so that it is no longer visible to consumers.

Method Details

createAPI

String createAPI(String userId,
 String apiManagerGUID,
 String apiManagerName,
 boolean apiManagerIsHome,
 String endpointGUID,
 APIProperties apiProperties)
          throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent an API.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiManagerIsHome - should the API be marked as owned by the API manager so others can not update?

endpointGUID - unique identifier of the endpoint where this API is located

apiProperties - properties to store

Returns:

unique identifier of the new metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createAPIFromTemplate

String createAPIFromTemplate(String userId,
 String apiManagerGUID,
 String apiManagerName,
 boolean apiManagerIsHome,
 String endpointGUID,
 String templateGUID,
 TemplateProperties templateProperties)
                      throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent an API using an existing metadata element as a template.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiManagerIsHome - should the API be marked as owned by the API manager so others can not update?

endpointGUID - unique identifier of the endpoint where this API is located

templateGUID - unique identifier of the metadata element to copy

templateProperties - properties that override the template

Returns:

unique identifier of the new metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

updateAPI

void updateAPI(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiGUID,
 boolean isMergeUpdate,
 APIProperties apiProperties)
        throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Update the metadata element representing an API.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiGUID - unique identifier of the metadata element to update

isMergeUpdate - are unspecified properties unchanged (true) or removed?

apiProperties - new properties for this element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

publishAPI

void publishAPI(String userId,
 String apiGUID)
         throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Update the zones for the API asset so that it becomes visible to consumers. (The zones are set to the list of zones in the publishedZones option configured for each instance of the Data Manager OMAS).

Parameters:

userId - calling user

apiGUID - unique identifier of the metadata element to publish

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

withdrawAPI

void withdrawAPI(String userId,
 String apiGUID)
          throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Update the zones for the API asset so that it is no longer visible to consumers. (The zones are set to the list of zones in the defaultZones option configured for each instance of the Data Manager OMAS. This is the setting when the API is first created).

Parameters:

userId - calling user

apiGUID - unique identifier of the metadata element to withdraw

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

removeAPI

void removeAPI(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiGUID,
 String qualifiedName)
        throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Remove the metadata element representing an API.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiGUID - unique identifier of the metadata element to remove

qualifiedName - unique name of the metadata element to remove

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

findAPIs

List<APIElement> findAPIs(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                   throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of API metadata elements that contain the search string. The search string is treated as a regular expression.

Parameters:

userId - calling user

searchString - string to find in the properties

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIsByName

List<APIElement> getAPIsByName(String userId,
 String name,
 int startFrom,
 int pageSize)
                        throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of API metadata elements with a matching qualified or display name. There are no wildcards supported on this request.

Parameters:

userId - calling user

name - name to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIsForAPIManager

List<APIElement> getAPIsForAPIManager(String userId,
 String apiManagerGUID,
 String apiManagerName,
 int startFrom,
 int pageSize)
                               throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of APIs created by this caller.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the API manager (API manager)

apiManagerName - unique name of software server capability representing the API manager (API manager)

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIsForEndpoint

List<APIElement> getAPIsForEndpoint(String userId,
 String endpointGUID,
 int startFrom,
 int pageSize)
                             throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of APIs connected to the requested endpoint.

Parameters:

userId - calling user

endpointGUID - unique identifier of the endpoint

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIByGUID

APIElement getAPIByGUID(String userId,
 String guid)
                 throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the API metadata element with the supplied unique identifier.

Parameters:

userId - calling user

guid - unique identifier of the requested metadata element

Returns:

matching metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createAPIOperation

String createAPIOperation(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiGUID,
 APIOperationProperties properties)
                   throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent an API Operation. This describes the structure of an operation supported by the API. The structure of this API Operation is added using API Parameter Lists. These parameter lists can have a simple type or a nested structure.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiGUID - unique identifier of an API

properties - properties about the API Operation

Returns:

unique identifier of the new API Operation

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createAPIOperationFromTemplate

String createAPIOperationFromTemplate(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String templateGUID,
 String apiGUID,
 TemplateProperties templateProperties)
                               throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent a an API Operation using an existing API Operation as a template.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

templateGUID - unique identifier of the metadata element to copy

apiGUID - unique identifier of the API where the API Operation is located

templateProperties - properties that override the template

Returns:

unique identifier of the new API Operation

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

updateAPIOperation

void updateAPIOperation(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiOperationGUID,
 boolean isMergeUpdate,
 APIOperationProperties properties)
                 throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Update the metadata element representing an API Operation.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiOperationGUID - unique identifier of the metadata element to update

isMergeUpdate - are unspecified properties unchanged (true) or removed?

properties - new properties for the metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

removeAPIOperation

void removeAPIOperation(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiOperationGUID,
 String qualifiedName)
                 throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Remove an API Operation.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiOperationGUID - unique identifier of the metadata element to remove

qualifiedName - unique name of the metadata element to remove

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

findAPIOperations

List<APIOperationElement> findAPIOperations(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                                     throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of API Operations metadata elements that contain the search string. The search string is treated as a regular expression.

Parameters:

userId - calling user

searchString - string to find in the properties

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getOperationsForAPI

List<APIOperationElement> getOperationsForAPI(String userId,
 String apiGUID,
 int startFrom,
 int pageSize)
                                       throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return the list of API Parameter Lists associated with an API Operation.

Parameters:

userId - calling user

apiGUID - unique identifier of the API to query

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of metadata elements describing the API Parameter Lists associated with the requested API Operation

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIOperationsByName

List<APIOperationElement> getAPIOperationsByName(String userId,
 String name,
 int startFrom,
 int pageSize)
                                          throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of API Operations metadata elements with a matching qualified or display name. There are no wildcards supported on this request.

Parameters:

userId - calling user

name - name to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIOperationByGUID

APIOperationElement getAPIOperationByGUID(String userId,
 String guid)
                                   throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the API Operation metadata element with the supplied unique identifier.

Parameters:

userId - calling user

guid - unique identifier of the requested metadata element

Returns:

requested metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createAPIParameterList

String createAPIParameterList(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiOperationGUID,
 APIParameterListType parameterListType,
 APIParameterListProperties properties)
                       throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent an API Operation's Parameter list. This describes the structure of the payload supported by the API's operation. The structure of this API Operation is added using API Parameter schema attributes. These parameters can have a simple type or a nested structure.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiOperationGUID - unique identifier of an APIOperation

parameterListType - is this a header, request or response

properties - properties about the API parameter list

Returns:

unique identifier of the new API parameter list

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createAPIParameterListFromTemplate

String createAPIParameterListFromTemplate(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String templateGUID,
 String apiOperationGUID,
 APIParameterListType parameterListType,
 TemplateProperties templateProperties)
                                   throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent a an API Parameter List using an existing API Parameter List as a template.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

templateGUID - unique identifier of the metadata element to copy

apiOperationGUID - unique identifier of the API where the API Operation is located

parameterListType - is this a header, request or response

templateProperties - properties that override the template

Returns:

unique identifier of the new API Parameter List

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

updateAPIParameterList

void updateAPIParameterList(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiParameterListGUID,
 boolean isMergeUpdate,
 APIParameterListProperties properties)
                     throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Update the metadata element representing an API ParameterList.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiParameterListGUID - unique identifier of the metadata element to update

isMergeUpdate - are unspecified properties unchanged (true) or removed?

properties - new properties for the metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

removeAPIParameterList

void removeAPIParameterList(String userId,
 String apiManagerGUID,
 String apiManagerName,
 String apiParameterListGUID,
 String qualifiedName)
                     throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Remove an API Parameter List and all of its parameters.

Parameters:

userId - calling user

apiManagerGUID - unique identifier of software server capability representing the caller

apiManagerName - unique name of software server capability representing the caller

apiParameterListGUID - unique identifier of the metadata element to remove

qualifiedName - unique name of the metadata element to remove

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

findAPIParameterLists

List<APIParameterListElement> findAPIParameterLists(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                                             throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of API Parameter List metadata elements that contain the search string. The search string is treated as a regular expression.

Parameters:

userId - calling user

searchString - string to find in the properties

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getParameterListsForAPIOperation

List<APIParameterListElement> getParameterListsForAPIOperation(String userId,
 String apiOperationGUID,
 int startFrom,
 int pageSize)
                                                        throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return the list of API Parameter Lists associated with an API Operation.

Parameters:

userId - calling user

apiOperationGUID - unique identifier of the API Operation to query

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of metadata elements describing the API Parameter Lists associated with the requested API Operation

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIParameterListsByName

List<APIParameterListElement> getAPIParameterListsByName(String userId,
 String name,
 int startFrom,
 int pageSize)
                                                  throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of API Parameter List metadata elements with a matching qualified or display name. There are no wildcards supported on this request.

Parameters:

userId - calling user

name - name to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAPIParameterListByGUID

APIParameterListElement getAPIParameterListByGUID(String userId,
 String guid)
                                           throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the API Parameter List metadata element with the supplied unique identifier.

Parameters:

userId - calling user

guid - unique identifier of the requested metadata element

Returns:

requested metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)