Migrating from the URL program-mapping file to URL mapping by server support

Migrate an entry in the URL program-mapping file to URL mapping by server support for a z/TPF HTTP server.

About this task

Each entry in the z/TPF HTTP server URL program-mapping file has its own line and contains information in one of the following formats:

```
URL REST_API_descriptor
```
```
URL program_name timeout_value
```

URL: The URL that is included in an HTTP client request.
REST_API_descriptor: An OpenAPI descriptor that contains information about how to process HTTP requests and responses for the specified URL.
program_name: The 4-character program name that is activated to process HTTP requests for the specified URL.
timeout_value: The amount of time (in milliseconds) that the z/TPF HTTP server waits for an HTTP response to an HTTP request.

The entries in the URL program-mapping file apply to all HTTP servers in the z/TPF system. To restrict entries from the URL program-mapping file to a particular HTTP server, use URL mapping by server support.

Procedure

If an entry in the URL program-mapping file contains a URL and OpenAPI descriptor name, complete the following steps to migrate this entry to URL mapping by server support. For example,
```
/mywebservices/restAPI* restAPI.swagger.json
```
1. Determine the HTTP server to process the HTTP requests and responses that are described in the OpenAPI descriptor file for the specified URL. You can also choose multiple HTTP servers to process these requests and responses.
2. Enter the ZHTPS command with the ADD parameter specified to add the OpenAPI descriptor file to the URL-mapping information for each of the HTTP servers from step 1. This command adds the information on all processors.
  For example, the following commands migrate the mapping information to the TPFHTTP1 and TPFHTTP2 HTTP servers.
```
ZHTPS ADD SERVER-TPFHTTP1 FILE-restAPI.swagger.json
ZHTPS ADD SERVER-TPFHTTP2 FILE-restAPI.swagger.json
```
3. Delete the entry from the URL program-mapping file.
4. Load the updated URL program-mapping file to the /etc/tpf_httpserver directory in the z/TPF file system.
5. Enter the ZHTPS command with the REFRESH and URL parameters specified on all processors.
If an entry in the URL program-mapping file contains a URL, program name, and timeout value, complete the following steps to migrate this entry to URL mapping by server support. This example shows two entries from the URL program-mapping file.
```
/http/sync                              QHTP      200
/http/async                             QHTP      200  
```
1. Create an OpenAPI descriptor.
  For example, you can create an OpenAPI descriptor called httpservices.swagger.json to provide information about how to process HTTP requests and responses for the /http/sync and http/async services.
```
{
   "swagger":"2.0",
   "info":{
      "description":"Provide services for http sync and async requests",
      "version":"1.0.0",
      "title":"HTTP Services"
   },
   "basePath":"/http",
   "schemes":[
      "http",
      "https"
   ],
   "paths":{
      "/sync":{
         "get":{
            "operationId":"htpdSyncGet",
            "responses":{
               "200":{
                  "description":"normal response"
               }
            }
         },
         "post":{
            "operationId":"htpdSyncPost",
            "responses":{
               "200":{
                  "description":"normal response"
               }
            }
         }
      },
      "/async":{
         "get":{
            "operationId":"htpdAsynGet",
            "responses":{
               "200":{
                  "description":"normal response"
               }
            }
         },
         "post":{
            "operationId":"htpdAsynPost",
            "responses":{
               "200":{
                  "description":"normal response"
               }
            }
         }
      }
   }
}
```
2. Create a z/TPF service descriptor, which is a JSON file and describes the implementation information for one or more z/TPF services.
  1. Specify HTTPProgram for the providerType.
  2. Specify the program name for the provider element.
  3. Specify the timeout value for the timeout element.
  The following example creates a z/TPF service descriptor called httpservices.srvc.json to provide the implementation details for these services.
```
{
   "version":1,
   "description":" Provide services for http sync and async requests",
   "providerType":"HTTPProgram",
   "provider":"QHTP",
   "timeout":200,
   "services": [
   { "operationId":"htpdSyncGet" },
   { "operationId":"htpdSyncPost" },
   { "operationId":"htpdAsynGet" },
   { "operationId":"htpdAsynPost" }
   ]
}
```
3. Load the OpenAPI descriptor and z/TPF service descriptor to the z/TPF file system.
4. Enter ZMDES DEPLOY FILE to mark the OpenAPI descriptor as available for use. For example, ZMDES DEPLOY FILE-httpservices.swagger.json.
5. Complete the steps for migrating an entry in the URL program-mapping file that contains a URL and OpenAPI descriptor name.
Alternatively, to migrate an entry in the URL program-mapping file to URL mapping by server support, you can use a REST API to add a service to an HTTP server instead of using the ZMDES DEPLOY and ZHTPS ADD commands. The advantage of this method is that you can create and deploy a new service to an HTTP server in one step. For more information, see REST APIs for service management.