alihan/fn-serverless
1
0
Fork 0
mirror of https://github.com/fnproject/fn.git synced 2022-10-28 21:29:17 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
d0ea620add6f56aaba799036b1d6cd96bbddf088
fn-serverless/docs/swagger.yml
Reed Allman 337e962416 add pagination to all list endpoints 
calls, apps, and routes listing were previously returning the entire data set,
which just won't scale. this adds pagination with cursoring forward to each of
these endpoints (see the [docs](docs/definitions.md)).

the patch is really mostly tests, shouldn't be that bad to pick through.

some blarble about implementation is in order:

calls are sorted by ids but allow searching within certain `created_at` ranges
(finally). this is because sorting by `created_at` isn't feasible when
combined with paging, as `created_at` is not guaranteed to be unique -- id's
are (eliding theoreticals). i.e. on a page boundary, if there are 200 calls
with the same `created_at`, providing a `cursor` of that `created_at` will
skip over the remaining N calls with that `created_at`.  also using id will be
better on the index anyway (well, less of them). yay having sortable ids! I
can't discern any issues doing this, as even if 200 calls have the same
created_at, they will have different ids, and the sort should allow paginating
them just fine. ids are also url safe, so the id works as the cursor value
just fine.

apps and routes are sorted by alphabetical order. as they aren't guaranteed to
be url safe, we are base64'ing them in the front end to a url safe format and
then returning them, and then base64 decoding them when we get them. this does
mean that they can be relatively large if the path/app is long, but if we
don't want to add ids then they were going to be pretty big anyway. a bonus
that this kind of obscures them. if somebody has better idea on formatting, by
all means.

notably, we are not using the sql paging facilities, and we are baking our own
based on cursors, which ends up being much more efficient for querying longer
lists of resources. this also should be easy to implement in other non-sql dbs
and the cursoring formats we can change on the fly since we are just exposing
them as opaque strings. the front end deals with the base64 / formatting, etc
and the back end is taking raw values (strfmt.DateTime or the id for calls).
the cursor that is being passed to/by the user is simply the last resource on the
previous page, so in theory we don't even need to return it, but it does make
it a little easier to use, also, cursor being blank on the last page depends
on page full-ness, so sometimes users will get a cursor when there are no
results on next page (1/N chance, and it's not really end of world -- actually
searching for the next thing would make things more complex). there are ample
tests for this behavior.

I've turned off all query parameters allowing `LIKE` queries on certain listing
endpoints, as we should not expose sql behavior through our API in the event
that we end up not using a sql db down the road. I think we should only allow
prefix matching, which sql can support as well as other types of databases
relatively cheaply, but this is not hooked up here as it didn't 'just work'
when I was fiddling with it (can add later, they're unnecessary and weren't
wired in before in front end).

* remove route listing across apps (unused)
* fix panic when doing `/app//`. this is prob possible for other types of
endpoints, out of scope here. added a guard in front of all endpoints for this
* adds `from_time` and `to_time` query parameters to calls, so you can e.g.
list the last hour of tasks. these are not required and default to
oldest/newest.
* hooked back up the datastore tests to the sql db, only run with sqlite atm,
but these are useful, added a lot to them too.
* added a bunch of tests to the front end, so pretty sure this all works now.
* added to swagger, we'll need to re-gen. also wrote some words about
pagination workings, I'm not sure how best to link to these, feedback welcome.
* not sure how we want to manage indexes, but we may need to add some (looking
at created_at, mostly)
* `?route` changed to `?path` in routes listing, to keep consistency with
everything else
* don't 404 when searching for calls where the route doesn't exist, just
return an empty list (it's a query param ffs)

closes #141
2017-09-20 06:50:49 -07:00

716 lines
18 KiB
YAML
Raw Blame History

swagger: '2.0'
info:
title: fn
description: The open source serverless platform.
version: "0.2.0"
# the domain of the service
host: "127.0.0.1:8080"
# array of all schemes that your API supports
schemes:
- https
- http
# will be prefixed to all paths
basePath: /v1
consumes:
- application/json
produces:
- application/json
paths:
/apps:
get:
summary: "Get all app names."
description: "Get a list of all the apps in the system, returned in alphabetical order."
tags:
- Apps
parameters:
- name: cursor
description: Cursor from previous response.next_cursor to begin results after, if any.
required: false
type: string
in: query
- name: per_page
description: Number of results to return, defaults to 30. Max of 100.
required: false
type: int
in: query
responses:
200:
description: List of apps.
schema:
$ref: '#/definitions/AppsWrapper'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
post:
summary: "Post new app"
description: "Insert a new app"
tags:
- Apps
parameters:
- name: body
in: body
description: App to post.
required: true
schema:
$ref: '#/definitions/AppWrapper'
responses:
200:
description: App details and stats.
schema:
$ref: '#/definitions/AppWrapper'
400:
description: Parameters are missing or invalid.
schema:
$ref: '#/definitions/Error'
409:
description: App already exists.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/apps/{app}:
delete:
summary: "Delete an app."
description: "Delete an app."
tags:
- Apps
parameters:
- name: app
in: path
description: Name of the app.
required: true
type: string
responses:
200:
description: Apps successfully deleted.
404:
description: App does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
get:
summary: "Get information for a app."
description: "This gives more details about a app, such as statistics."
tags:
- Apps
parameters:
- name: app
in: path
description: name of the app.
required: true
type: string
responses:
200:
description: App details and stats.
schema:
$ref: '#/definitions/AppWrapper'
404:
description: App does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
patch:
summary: "Updates an app."
description: "You can set app level settings here. "
tags:
- Apps
parameters:
- name: app
in: path
description: name of the app.
required: true
type: string
- name: body
in: body
description: App to post.
required: true
schema:
$ref: '#/definitions/AppWrapper'
responses:
200:
description: App details and stats.
schema:
$ref: '#/definitions/AppWrapper'
400:
description: Parameters are missing or invalid.
schema:
$ref: '#/definitions/Error'
404:
description: App does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/apps/{app}/routes:
post:
summary: Create new Route
description: Create a new route in an app, if app doesn't exists, it creates the app. Post does not skip validation of zero values.
tags:
- Routes
parameters:
- name: app
in: path
description: name of the app.
required: true
type: string
- name: body
in: body
description: One route to post.
required: true
schema:
$ref: '#/definitions/RouteWrapper'
responses:
200:
description: Route created
schema:
$ref: '#/definitions/RouteWrapper'
400:
description: Invalid route due to parameters being missing or invalid.
schema:
$ref: '#/definitions/Error'
409:
description: Route already exists.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
get:
summary: Get route list by app name.
description: This will list routes for a particular app, returned in alphabetical order.
tags:
- Routes
parameters:
- name: app
in: path
description: Name of app for this set of routes.
required: true
type: string
- name: image
description: Route image to match, exact.
required: false
type: string
in: query
- name: cursor
description: Cursor from previous response.next_cursor to begin results after, if any.
required: false
type: string
in: query
- name: per_page
description: Number of results to return, defaults to 30. Max of 100.
required: false
type: int
in: query
responses:
200:
description: Route information
schema:
$ref: '#/definitions/RoutesWrapper'
404:
description: App does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/apps/{app}/routes/{route}:
put:
summary: Create a Route if it does not exist. Update if it does. Will also create app if it does not exist. Put does not skip validation of zero values
description: Update or Create a route
tags:
- Routes
parameters:
- name: app
in: path
description: name of the app.
required: true
type: string
- name: route
in: path
description: route path.
required: true
type: string
- name: body
in: body
description: One route to post.
required: true
schema:
$ref: '#/definitions/RouteWrapper'
responses:
200:
description: Route created or updated
schema:
$ref: '#/definitions/RouteWrapper'
400:
description: Invalid route due to parameters being missing or invalid.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
patch:
summary: Update a Route, Fails if the route or app does not exist. Accepts partial updates / skips validation of zero values.
description: Update a route
tags:
- Routes
parameters:
- name: app
in: path
description: name of the app.
required: true
type: string
- name: route
in: path
description: route path.
required: true
type: string
- name: body
in: body
description: One route to post.
required: true
schema:
$ref: '#/definitions/RouteWrapper'
responses:
200:
description: Route updated
schema:
$ref: '#/definitions/RouteWrapper'
400:
description: Invalid route due to parameters being missing or invalid.
schema:
$ref: '#/definitions/Error'
404:
description: App / Route does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
get:
summary: Gets route by name
description: Gets a route by name.
tags:
- Routes
parameters:
- name: app
in: path
description: Name of app for this set of routes.
required: true
type: string
- name: route
in: path
description: Route name
required: true
type: string
responses:
200:
description: Route information
schema:
$ref: '#/definitions/RouteWrapper'
404:
description: Route does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
delete:
summary: Deletes the route
tags:
- Routes
description: Deletes the route.
parameters:
- name: app
in: path
description: Name of app for this set of routes.
required: true
type: string
- name: route
in: path
description: Route name
required: true
type: string
responses:
200:
description: Route successfully deleted.
404:
description: Route does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/apps/{app}/calls/{call}/log:
get:
summary: Get call logs
description: Get call logs
tags:
- Call
- Log
parameters:
- name: app
description: App Name
required: true
type: string
in: path
- name: call
description: Call ID.
required: true
type: string
in: path
responses:
200:
description: Log found
schema:
$ref: '#/definitions/LogWrapper'
404:
description: Log not found.
schema:
$ref: '#/definitions/Error'
delete:
summary: Delete call log entry
description: Delete call log entry
tags:
- Call
- Log
parameters:
- name: call
description: Call ID.
required: true
type: string
in: path
- name: app
description: App name.
required: true
type: string
in: path
responses:
202:
description: Log delete request accepted
404:
description: Does not exist.
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/apps/{app}/calls/{call}:
get:
summary: Get call information
description: Get call information
tags:
- Call
parameters:
- name: app
description: app name
required: true
type: string
in: path
- name: call
description: Call ID.
required: true
type: string
in: path
responses:
200:
description: Call found
schema:
$ref: '#/definitions/CallWrapper'
404:
description: Call not found.
schema:
$ref: '#/definitions/Error'
/apps/{app}/calls:
get:
summary: Get app-bound calls.
description: Get app-bound calls can filter to route-bound calls, results returned in created_at, descending order (newest first).
tags:
- Call
parameters:
- name: app
description: App name.
required: true
type: string
in: path
- name: path
description: Route path to match, exact.
required: false
type: string
in: query
- name: cursor
description: Cursor from previous response.next_cursor to begin results after, if any.
required: false
type: string
in: query
- name: per_page
description: Number of results to return, defaults to 30. Max of 100.
required: false
type: int
in: query
- name: from_time
description: Unix timestamp in seconds, of call.created_at to begin the results at, default 0.
required: false
type: int
in: query
- name: to_time
description: Unix timestamp in seconds, of call.created_at to end the results at, defaults to latest.
required: false
type: int
in: query
responses:
200:
description: Calls found
schema:
$ref: '#/definitions/CallsWrapper'
404:
description: Calls not found.
schema:
$ref: '#/definitions/Error'
definitions:
Route:
type: object
properties:
path:
type: string
description: URL path that will be matched to this route
readOnly: true
image:
description: Name of Docker image to use in this route. You should include the image tag, which should be a version number, to be more accurate. Can be overridden on a per route basis with route.image.
type: string
headers:
type: object
description: Map of http headers that will be sent with the response
additionalProperties:
type: array
items:
type: string
memory:
type: integer
format: uint64
description: Max usable memory for this route (MiB).
type:
enum:
- sync
- async
description: Route type
type: string
format:
enum:
- default
- http
- json
description: Payload format sent into function.
type: string
config:
type: object
description: Route configuration - overrides application configuration
additionalProperties:
type: string
timeout:
type: integer
default: 30
format: int32
description: Timeout for executions of this route. Value in Seconds
idle_timeout:
type: integer
default: 30
format: int32
description: Hot functions idle timeout before termination. Value in Seconds
App:
type: object
properties:
name:
type: string
description: "Name of this app. Must be different than the image name. Can ony contain alphanumeric, -, and _."
readOnly: true
config:
type: object
description: Application configuration, applied to all routes.
additionalProperties:
type: string
Version:
type: object
properties:
version:
type: string
readOnly: true
RoutesWrapper:
type: object
required:
- routes
properties:
next_cursor:
type: string
description: cursor to send with subsequent request to receive the next page, if non-empty
readOnly: true
routes:
type: array
items:
$ref: '#/definitions/Route'
error:
$ref: '#/definitions/ErrorBody'
RouteWrapper:
type: object
required:
- route
properties:
message:
type: string
error:
$ref: '#/definitions/ErrorBody'
route:
$ref: '#/definitions/Route'
AppsWrapper:
type: object
required:
- apps
properties:
next_cursor:
type: string
description: cursor to send with subsequent request to receive the next page, if non-empty
readOnly: true
apps:
type: array
items:
$ref: '#/definitions/App'
error:
$ref: '#/definitions/ErrorBody'
AppWrapper:
type: object
required:
- app
properties:
app:
$ref: '#/definitions/App'
error:
$ref: '#/definitions/ErrorBody'
CallsWrapper:
type: object
required:
- calls
properties:
next_cursor:
type: string
description: cursor to send with subsequent request to receive the next page, if non-empty
readOnly: true
calls:
type: array
items:
$ref: '#/definitions/Call'
error:
$ref: '#/definitions/ErrorBody'
CallWrapper:
type: object
required:
- call
properties:
call:
$ref: '#/definitions/Call'
description: "Call object."
LogWrapper:
type: object
required:
- log
properties:
log:
$ref: '#/definitions/Log'
description: "Call log entry."
Log:
type: object
properties:
call_id:
type: string
description: Call UUID ID
log:
type: string # maybe bytes, long logs wouldn't fit into string type
Call:
type: object
properties:
id:
type: string
description: Call UUID ID.
readOnly: true
status:
type: string
description: Call execution status.
readOnly: true
app_name:
type: string
description: App name that is assigned to a route that is being executed.
readOnly: true
path:
type: string
description: App route that is being executed.
readOnly: true
created_at:
type: string
format: date-time
description: Time when call was submitted. Always in UTC.
readOnly: true
started_at:
type: string
format: date-time
description: Time when call started execution. Always in UTC.
readOnly: true
completed_at:
type: string
format: date-time
description: Time when call completed, whether it was successul or failed. Always in UTC.
readOnly: true
ErrorBody:
type: object
properties:
message:
type: string
readOnly: true
fields:
type: string
readOnly: true
Error:
type: object
properties:
error:
$ref: '#/definitions/ErrorBody'
Reference in New Issue View Git Blame Copy Permalink