Function Contacts_API(@API) /*********************************************************************************************************************** This program is proprietary and is not to be used by or disclosed to others, nor is it to be copied without written permission from SRP Computer Solutions, Inc. Name : Contacts_API Description : API logic for the Contacts resource. Notes : All web APIs should include the API_SETUP insert. This will provide several useful variables: HTTPMethod - The HTTP Method (Verb) submitted by the client (e.g., GET, POST, etc.) APIURL - The URL for the API entry point (e.g., api.mysite.com/v1). FullEndpointURL - The URL submitted by the client, including query params. FullEndpointURLNoQuery - The URL submitted by the client, excluding query params. ParentURL - The URL path preceeding the current endpoint. the SelfURL. CurrentAPI - The name of this stored procedure. Parameters : API [in] -- Web API to process. Format is [APIPattern].[HTTPMethod]: - APIPattern must follow this structure [.ID.[]] - HTTPMethod can be any valid HTTP method, e.g., GET, POST, PUT, DELETE, etc. Examples: - Contacts.POST - Contacts.ID.PUT - Contacts.ID.firstName.GET Response [out] -- Response to be sent back to the Controller (HTTP_MCP) or requesting procedure. Web API services do not rely upon anything being returned in the response. This is what the various services like SetResponseBody and SetResponseStatus services are for. A response value is only helpful if the developers want to use it for debug purposes. History : (Date, Initials, Notes) 11/17/18 dmb Original programmer. 04/09/19 dmb [SRPFW-271] Replace FullEndpointURL with FullEndpointURLNoQuery in the GetObjects service within the Contacts.GET API to avoid query params in the embedded object self URLs. 05/28/19 dmb [SRPFW-274] Replace all references to AddLinkRelationships with AddLinkRelations. 05/31/19 dmb [SRPFW-276] Update contacts.ID.GET API by removing unnecessary call to the GetDatabaseItem service. 01/23/20 dmb [SRPFW-296] Add matching HEAD APIs for all GET APIs. ***********************************************************************************************************************/ #pragma precomp SRP_PreCompiler $insert APP_INSERTS $insert API_SETUP $insert HTTP_INSERTS $insert CONTACTS_EQUATES Declare function Database_Services Declare subroutine RList GoToAPI else // The specific resource endpoint doesn't have a API handler yet. HTTP_Services('SetResponseStatus', 204, 'This is a valid endpoint but a web API handler has not yet been created.') end Return Response OR '' //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// // Endpoint Handlers //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// API contacts.HEAD API contacts.GET DisplayColumnNames = 'first_name' : @FM : 'last_name' : @FM : 'email' If HTTP_Services('GetHTTPGetString') NE '' then // This means the URL ends with /contacts?{property}={value}. The client is searching for one or more contacts // that match the query parameters. This is equivalent to doing a filtered RLIST search. // Get the query string passed into the URL. GetString = HTTP_Services('GetHTTPGetString') // Get the name of the property being queried. Property = GetString[1, 'F='] // Get the value being searched for. Value = HTTP_Services('GetQueryField', Property) // Get the database columns for the table. ColumnNames = HTTP_Resource_Services('GetColumnNames', 'CONTACTS') ColumnName = Property Convert @Lower_Case to @Upper_Case in ColumnName // Verify the property matches a valid column in the table. Locate ColumnName in ColumnNames using @FM setting fPos then // Use the GetDatabaseItems service to perform the search and prepare the HAL+JSON response. If a more complex // or optimized solution is needed, then replace the following with custom code. Filter = 'SELECT CONTACTS WITH ' : ColumnName : ' CONTAINING ' : Quote(Value) // The GetDatabaseItems service will return all database column values unless otherwise specified. Since a query // search might generated several results, it is sometimes best to pass in just those columns that are important // for the query result. Locate ColumnName in DisplayColumnNames using @FM setting fPos else // Make sure the property being searched is included in the columns being returned. DisplayColumnNames := @FM : Property end end else // This is not a valid property, which means the URL does not resolve. Set a 404 error. Add a description if // desired. Error_Services('Add', ColumnName : ' is not a valid column in the CONTACTS table.') HTTP_Services('SetResponseError', '', '', 404, Error_Services('GetMessage'), FullEndpointURL) end end else // This means the URL ends with /contacts. The client is requesting all resources available at this URL. // This is equivalent to performing an unfiltered SELECT statement. Pass in an empty filter. Filter = '' end If Error_Services('NoError') then objResource = HTTP_Resource_Services('GetObject') If Error_Services('NoError') then objContacts = HTTP_Resource_Services('GetObjects', 'CONTACTS', Filter, DisplayColumnNames, '', '', '', '', FullEndpointURLNoQuery) HTTP_Resource_Services('AddEmbeddedResources', objResource, 'contacts', objContacts) // Add _links sub-properties for HAL implementation. Rels = 'self' : @FM : 'apiEntryPoint' URLs = FullEndpointURL : @FM : ParentURL HTTP_Resource_Services('AddLinkRelations', objResource, Rels, URLs) If Error_Services('NoError') then // Serialize the object into a JSON string. jsonResource = HTTP_Resource_Services('GetSerializedResource', objResource) // Set the response body with the JSON string and set the Content-Type response header. HTTP_Services('SetResponseBody', jsonResource, False$, 'application/hal+json') end else HTTP_Services('SetResponseError', '', '', 500, Error_Services('GetMessage'), FullEndpointURL) end end else HTTP_Services('SetResponseError', '', '', 500, Error_Services('GetMessage'), FullEndpointURL) end end end api API contacts.POST * HTTP_Resource_Services('PostDatabaseItem', 'CONTACTS', FullEndpointURL) * Call Push.Session(Hold1, Hold2, Hold3, Hold4, Hold5, Hold6) * Call Pop.Session(Hold1, Hold2, Hold3, Hold4, Hold5, Hold6) end api API contacts.ID.HEAD API contacts.ID.GET KeyID = EndpointSegment // Create a new specific contacts resource object using the passed in resource ID to initialize the content. objResource = HTTP_Resource_Services('GetObject', 'CONTACTS', KeyID, '', '', '', '', '', '', '', '', 1) If Error_Services('NoError') then // Add _links sub-properties for HAL implementation. CollectionURL = ParentURL Names = 'self,collection' URLs = FullEndpointURL : ',' : CollectionURL HTTP_Resource_Services('AddLinkRelations', objResource, Names, URLs) end If Error_Services('NoError') then // If there is a picture related to this contact, add another _links sub-property for the URL. PictureValue = SRP_JSON(objResource, 'GetValue', 'picture', '') If PictureValue NE '' then ImageURL = FullEndpointURL : '/picture' HTTP_Resource_Services('AddLinkRelations', objResource, 'picture', ImageURL) end end If Error_Services('NoError') then // Serialize the object into a JSON string. jsonResource = HTTP_Resource_Services('GetSerializedResource', objResource) // Set the response body with the JSON string and set the Content-Type response header. HTTP_Services('SetResponseBody', jsonResource, False$, 'application/hal+json') end else HTTP_Services('SetResponseError', '', '', 500, Error_Services('GetMessage'), FullEndpointURL) end end api API contacts.ID.PATCH KeyID = EndpointSegment HTTP_Resource_Services('PatchDatabaseItem', 'CONTACTS', FullEndpointURL, KeyID) end api API contacts.ID.PUT KeyID = EndpointSegment HTTP_Resource_Services('PutDatabaseItem', 'CONTACTS', FullEndpointURL, KeyID) end api API contacts.ID.DELETE KeyID = EndpointSegment HTTP_Resource_Services('DeleteDatabaseItem', 'CONTACTS', KeyID) end api API contacts.ID.first_name.HEAD API contacts.ID.first_name.GET KeyID = ParentSegment objResource = HTTP_Resource_Services('GetObject', 'CONTACTS', KeyID, 'first_name') If Error_Services('NoError') then // Add _links sub-properties for HAL implementation. ResourceURL = ParentURL Names = 'self' : @FM : 'resource' URLs = FullEndpointURL : @FM : ResourceURL HTTP_Resource_Services('AddLinkRelations', objResource, Names, URLs) end If Error_Services('NoError') then // Serialize the object into a JSON string. jsonResource = HTTP_Resource_Services('GetSerializedResource', objResource) // Set the response body with the JSON string and set the Content-Type response header. HTTP_Services('SetResponseBody', jsonResource, False$, 'application/hal+json') end else HTTP_Services('SetResponseError', '', '', 500, Error_Services('GetMessage'), FullEndpointURL) end end api API contacts.ID.first_name.PATCH KeyID = ParentSegment HAL = HTTP_Resource_Services('PatchDatabaseItem', 'CONTACTS', FullEndpointURL, KeyID, 'first_name') end api API contacts.ID.last_name.HEAD API contacts.ID.last_name.GET KeyID = ParentSegment objResource = HTTP_Resource_Services('GetObject', 'CONTACTS', KeyID, 'last_name') If Error_Services('NoError') then // Add _links sub-properties for HAL implementation. ResourceURL = ParentURL Names = 'self' : @FM : 'resource' URLs = FullEndpointURL : @FM : ResourceURL HTTP_Resource_Services('AddLinkRelations', objResource, Names, URLs) end If Error_Services('NoError') then // Serialize the object into a JSON string. jsonResource = HTTP_Resource_Services('GetSerializedResource', objResource) // Set the response body with the JSON string and set the Content-Type response header. HTTP_Services('SetResponseBody', jsonResource, False$, 'application/hal+json') end else HTTP_Services('SetResponseError', '', '', 500, Error_Services('GetMessage'), FullEndpointURL) end end api API contacts.ID.last_name.PATCH KeyID = ParentSegment HAL = HTTP_Resource_Services('PatchDatabaseItem', 'CONTACTS', FullEndpointURL, KeyID, 'last_name') end api API contacts.ID.first_name.PUT KeyID = ParentSegment HAL = HTTP_Resource_Services('PatchDatabaseItem', 'CONTACTS', FullEndpointURL, KeyID, 'first_name') end api API contacts.ID.last_name.PUT KeyID = ParentSegment HAL = HTTP_Resource_Services('PatchDatabaseItem', 'CONTACTS', FullEndpointURL, KeyID, 'last_name') end api