Add pagination and Changes-since filter support for os-migrations.

This patch adds pagination support and changes-since filter
for os-migrations API.

Users can now use 'limit' and 'marker' to perform paginate
query of running migrations list. Users can also filter the
results according to the migrations' updated time.

The ``GET /os-migrations`` and server migrations APIs will now
return a uuid value in addition to the migrations id in the response,
and the query parameter schema of the ``GET /os-migrations`` API no
longer allows additional properties.

Co-Authored-By: Yikun Jiang <yikunkero@gmail.com>

Implement: blueprint add-pagination-and-change-since-for-migration-list
Change-Id: I7e01f95d7173d9217f76e838b3ea71555151ef56

api-ref/source/os-migrations.inc

@@ -1,14 +1,11 @@
 .. -*- rst -*-
 
 =========================================
- Migrations (os-migrations) (frozen)
+ Migrations (os-migrations)
 =========================================
 
 Shows data on migrations.
 
-.. warning:: The old top-level resource `/os-migrations` is frozen,
-             it won't be extended anymore. Use /servers/{uuid}/migrations instead.
-
 List Migrations
 ===============
 
@@ -22,7 +19,7 @@ this operation. Cloud providers can change these permissions through the
 
 Normal response codes: 200
 
-Error response codes: unauthorized(401), forbidden(403)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
 
 Request
 -------
@@ -35,6 +32,9 @@ Request
   - migration_type: migration_type
   - source_compute: migration_source_compute
   - status: migration_status
+  - limit: migration_limit
+  - marker: migration_marker
+  - changes-since: changes_since_migration
 
 Response
 --------
@@ -55,9 +55,21 @@ Response
   - updated_at: updated
   - migration_type: migration_type_2_23
   - links: migration_links_2_23
+  - uuid: migration_uuid
+  - migrations_links: migration_next_links_2_59
 
 **Example List Migrations: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/os-migrations/migrations-get.json
    :language: javascript
 
+**Example List Migrations (v2.59):**
+
+.. literalinclude:: ../../doc/api_samples/os-migrations/v2.59/migrations-get.json
+   :language: javascript
+
+**Example List Migrations With Links (v2.59):**
+
+.. literalinclude:: ../../doc/api_samples/os-migrations/v2.59/migrations-get-with-limit.json
+   :language: javascript
+