# Use this cell to test the output
!curl http://localhost:5000/datetime/v1/timezones -vk

"""
Explanation: Pagination and encapsulation:
In our standardization policy, we defined a common set of pagination parameters.
Moreover we stated that responses should always be enclosed in json objects, eg:

always return something that is extensible like 

```
GET /timezones
{ 
 "entries": [ "you", "can", "always", "add", "new", "keys" ]
}
```

don't return string, number or array, because 

```
GET /dont-do-this
[ "you can't", "extend them"]
```
Support pagination in get /timezones
We want to provide a /timezones path listing all the timezones supported 
by get /echo
Our goal is the following:

when invoking /datetime/v1/timezones the API will return 
  the supported timezones in pytz.all_timezones;
to limit resource consumption the server will return:
by default 5 entries 
at most 10 entries
the response is enveloped in the following example json object:

{ 
  "entries": [ "Europe/Rome", "UTC", .. ],
  "count": 5,
  "offset": 10
}

the status code for a successful response is 200

Remember: pagination should be implemented using a common
set of parameters to use. Our choice is:

limit: max number of entries to retrieve
offset: the number of entries to skip in a paginated request
cursor: an identifier (cursor) of the first entry to be returned
Slack APIs provide an example of cursor-based pagination

Exercise: write /timezone specs
Edit the ex-08-pagination-ok.yaml and write the timezones specifications:
1- define the new Timezones schema to be used in the response;
2- define the new /timezones path supporting the get method:

always write proper summary and description fields

3- get /timezones possible responses are:

200 returning a Timezones in json format, with a complete example for mocks
429 and 503 returning a problem+json

4- this operation is not authenticated
5- don't forget operationId: get_timezones !
Hint: feel free to reuse as much yaml code as possible.
Exercise: test /timezones mocks
Run your spec in the terminal and check that it properly returns the mock objects.
Use 
connexion run --mock all /code/notebooks/oas3/ex-08-pagination-ok.yaml
End of explanation
"""


# Use this cell to test your api

"""
Explanation: Path parameters
OAS3 allows to specify path parameters:

in the path, with braces eg. {continent}
in parameters with the remaining details.

REMEMBER: path parameters are always required so you must define a new path
   and a new operationId: get_timezones_by_continent
paths: 
  /timezones/{continent}:
    get:
      ...
      parameters:
      - name: continent
        in: path
        required: true
        schema:
          type: string
  /timezones:
    ...
    definition without path-parameters
    ...
Exercise: adding path parameter to /timezones
Let's add a continent path parameter to /timezones:

create a #/components/parameters/continent_path parameter definition;
add the continent_path query parameter to get /timezones/{continent} path checking
  the official OAS 3.0.2 documentation
add a 404 Not Found response in case the continent is not present

Finally, check that you can run the spec.
connexion run --mock all /code/notebooks/oas3/ex-08-pagination-ok.yaml
End of explanation
"""


# Check that default works
!curl http://localhost:5000/datetime/v1/timezones -kv

"""
Explanation: Exercise:  implement get_timezones operations
Let's implement the get_timezones operation in api.py such that:

is throttled
takes the limit and offset parameters;
returns a Timezones object containing all the timezones in pytz.all_timezones between offset and offset+limit
End of explanation
"""


### Exercise solution


!grep  '^def get_timezones' oas3/api-solution.py -A20 -B1

"""
Explanation: Exercise:  implement get_timezones_by_continent operations
Let's implement the get_timezones_by_continent operation in api.py such that:

extends get_timezones behavior;

returns a Timezones object containing all the timezones in the given continent, eg:


Europe -> [ "Europe/London", "Europe/Rome", ... ]
End of explanation
"""


render_markdown(f'''
Play a bit with the [Swagger UI]({api_server_url('ui')})

and try making a request!
''')

# Use out-of-bound offset
!curl http://localhost:5000/datetime/v1/timezones?offset=800 -kv

# Pick in the middle
!curl 'http://localhost:5000/datetime/v1/timezones?offset=450&limit=2' -kv

# Pick in the middle
!curl 'http://localhost:5000/datetime/v1/timezones/Europe?limit=2' -kv


"""
Explanation: Now  run the spec in a terminal using
cd /code/notebooks/oas3/
connexion run /code/notebooks/oas3/ex-08-pagination-ok.yaml
End of explanation
"""


