Create additional phonebook API methods

This topic shows you how to define another path and data mapping for the PUT, GET, and DELETE verbs. The steps in this topic are optional.

About this task

In this step, you will define a new path, /phonebook/contacts/{lastName}, and the data mapping for the associated PUT, GET, and DELETE verbs.

Table 1. Output for the display and delete actions

Action	HTTP Verb	Fields to return
Display a contact	GET	IN-COMMAND to be assigned a value of DISPLAY. Fields to return: OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE LAST-NAME, FIRST-NAME, EXTENSION, and ZIP-CODE.
Update a contact	PUT	IN-COMMAND to be assigned a value of UPDATE. Fields to return: OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE: To allow for validation of the updated contact record.
Delete a contact	DELETE	IN-COMMAND to be assigned a value of DELETE. Fields to return: OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME: To allow for validation of the deleted record.

To display, update, or delete a contact record for a given last name, define the path value and the map the request and response message for the action:

1. In the z/OS® Connect API toolkit where the package.xml is displayed, add a path by clicking the Add a new path button () next to the Path label.

   

2. Enter the API path and the path parameter, lastName, enclosed in curly brackets. In this case, it is /contacts/{lastName}
3. Remove the POST method by clicking the remove button () next to the method.

The GET method

For the GET method (querying a contact record by last name), map the data structure between the service JSON schema and the HTTP request and response messages.

4. For the GET method, click Service next to the method, select the phonebook service archive file, and click OK.
5. Click File > Save or press Ctrl-S to save the service association.
6. Click Mapping next to the GET method and select Open Request Mapping.
7. Right-click the IN_COMMAND field in the service definition on the right, and select Add Assign transform.
   An Assign box shows up in the middle.
8. Click the Assign box, and the Transform - Assign properties view opens.
9. For the Value field, enter DISPLAY.
10. Because only the last name is needed for the request and the other fields are not needed, remove those fields so they are hidden from the client.
    1. Hold down the Ctrl key to select multiple fields: IN_EXTENSION, IN_FIRST_NAME, and IN_ZIP_CODE.
    2. Right-click and select Add Remove transform.

    

    The last step is to map the path parameter lastName from the HTTP Request section to the IN_LAST_NAME field.

    Tip: You can right-click the field to undo an action, or right-click the added action button to delete the action.
11. Click and drag the lastName path parameter field in the HTTP Request section to the IN_LAST_NAME field on the right.

    

    No JSON body is sent in with this request. All the information needed to display a contact record is carried on the URI with the path parameter.

12. Click File > Save (Ctrl-S) to save your request mapping.
13. Close the request mapping tab.

    The next step is to map the response. For the given last name, we want to return all fields except the OUT_COMMAND field, so we need to remove this field from the response.

14. Click Mapping next to the GET method and select Open Response Mapping.
15. Right-click OUT_COMMAND on the right, and select Add Remove transform.

    

16. Click File > Save (Ctrl-S) to save your response mapping and close the response tab.

The PUT method

For the PUT method (updating a record), the request and response mapping is similar to the GET method. The key tasks are as follows:

• Assign a service that is associated with this method.
• Assign a static value to the IN_COMMAND field. The command to update a record in the phonebook application is UPDATE, so set the static value to UPDATE.
• The lastName path parameter is the key and its value needs to be moved to the IN_LAST_NAME field.
• The IN_FIRST_NAME, IN_EXTENSION and IN_ZIP_CODE fields need to be exposed in the JSON body for this request for users to update.

17. Map the request for the PUT method so the mapping looks as follows:

    

18. Save your changes.
19. Close the request tab.

    Next map the response message. All fields should be returned to allow users to validate their updates.

20. Map the response for the PUT method as follows:

    

21. Save your changes and close the response tab.
    Tip: With this mapping design, if only the extension for a specified last name is provided in the request message, the first name and zip code fields will be updated as blank. Ensuring that field values are not incorrectly wiped out would be the responsibility of the mobile application developer.

The DELETE method

For the DELETE method (deleting a record), the key mapping tasks are as follows:

• Assign the service that is associated with this method and save
• Assign a static value to the IN_COMMAND field. In this case, the command to delete a record in the phonebook application is DELETE, so set the value to DELETE.
• The lastName path parameter is the key and its value needs to be moved to the IN_LAST_NAME field.
• No fields need to be exposed in the request, so IN_EXTENSION, IN_FIRST_NAME, and IN_ZIP_CODE should be removed.

22. Map the request for the DELETE method so the mapping looks as follows:

    

23. Save your changes and close the request tab.

    Next map the response message. For a delete operation, all we are interested in is whether the action succeeded. This information is indicated in OUT_MESSAGE. Therefore all fields, except OUT_MESSAGE, should be removed.

24. Map the response for the DELETE request as follows:

    

25. Save your changes and close the response tab.

Results

The API is now completed.