[][src]Crate dropshot

Dropshot is a general-purpose crate for exposing REST APIs from a Rust program. Planned highlights include:

  • Suitability for production use on a largely untrusted network. Dropshot-based systems should be high-performing, reliable, debuggable, and secure against basic denial of service attacks (intentional or otherwise).

  • First-class OpenAPI support, in the form of precise OpenAPI specs generated directly from code. This works because the functions that serve HTTP resources consume arguments and return values of specific types from which a schema can be statically generated.

  • Ease of integrating into a diverse team. An important use case for Dropshot consumers is to have a team of engineers where individuals might add a few endpoints at a time to a complex server, and it should be relatively easy to do this. Part of this means an emphasis on the principle of least surprise: like Rust itself, we may choose abstractions that require more time to learn up front in order to make it harder to accidentally build systems that will not perform, will crash in corner cases, etc.

By "REST API", we primarily mean an API built atop existing HTTP primitives, organized into hierarchical resources, and providing consistent, idempotent mechanisms to create, update, list, and delete those resources. "REST" can mean a range of things depending on who you talk to, and some people are dogmatic about what is or isn't RESTy. We find such dogma not only unhelpful, but poorly defined. (Consider such a simple case as trying to update a resource in a REST API. Popular APIs sometimes use PUT, PATCH, or POST for the verb; and JSON Merge Patch or JSON Patch as the format. (sometimes without even knowing it!). There's hardly a clear standard, yet this is a really basic operation for any REST API.)

For a discussion of alternative crates considered, see Oxide RFD 10.

We hope Dropshot will be fairly general-purpose, but it's primarily intended to address the needs of the Oxide control plane.


The bare minimum might look like this:

use dropshot::ApiDescription;
use dropshot::ConfigDropshot;
use dropshot::ConfigLogging;
use dropshot::ConfigLoggingLevel;
use dropshot::HttpServer;
use std::sync::Arc;

async fn main() -> Result<(), String> {
    // Set up a logger.
    let log =
        ConfigLogging::StderrTerminal {
            level: ConfigLoggingLevel::Info,
        .map_err(|e| e.to_string())?;

    // Describe the API.
    let mut api = ApiDescription::new();
    // Register API functions -- see detailed example or ApiDescription docs.

    // Start the server.
    let mut server =
            &ConfigDropshot {
                bind_address: "".parse().unwrap(),
        .map_err(|error| format!("failed to start server: {}", error))?;

    let server_task = server.run();

This server returns a 404 for all resources because no API functions were registered. See examples/basic.rs for a simple, documented example that provides a few resources using shared state.

For a given ApiDescription, you can also print out an OpenAPI spec describing the API. See ApiDescription::print_openapi.

API Handler Functions

HTTP talks about resources. For a REST API, we often talk about endpoints or operations, which are identified by a combination of the HTTP method and the URI path.

Example endpoints for a resource called a "project" might include:

  • GET /projects (list projects)
  • POST /projects (one way to create a project)
  • GET /projects/my_project (fetch one project)
  • PUT /projects/my_project (update (or possibly create) a project)
  • DELETE /projects/my_project (delete a project)

With Dropshot, an incoming request for a given API endpoint is handled by a particular Rust function. That function is called an entrypoint, an endpoint handler, or a handler function. When you set up a Dropshot server, you configure the set of available API endpoints and which functions will handle each one by setting up an ApiDescription.

Typically, you define an endpoint with a handler function by using the endpoint macro. Here's an example of a single endpoint that lists a hardcoded project:

use dropshot::endpoint;
use dropshot::ApiDescription;
use dropshot::HttpError;
use dropshot::HttpResponseOk;
use dropshot::RequestContext;
use http::Method;
use schemars::JsonSchema;
use serde::Serialize;
use std::sync::Arc;

/** Represents a project in our API */
#[derive(Serialize, JsonSchema)]
struct Project {
    /** name of the project */
    name: String,

/** Fetch a project. */
#[endpoint {
    method = GET,
    path = "/projects/project1",
async fn myapi_projects_get_project(
    rqctx: Arc<RequestContext>,
) -> Result<HttpResponseOk<Project>, HttpError>
   let project = Project { name: String::from("project1") };

fn main() {
    let mut api = ApiDescription::new();

     * Register our endpoint and its handler function.  The "endpoint" macro
     * specifies the HTTP method and URI path that identify the endpoint,
     * allowing this metadata to live right alongside the handler function.

    /* ... (use `api` to set up an `HttpServer` ) */

There's quite a lot going on here:

  • The endpoint macro specifies the HTTP method and URI path. When we invoke ApiDescription::register(), this information is used to register the endpoint that will be handled by our function.
  • The signature of our function indicates that on success, it returns a HttpResponseOk<Project>. This means that the function will return an HTTP 200 status code ("OK") with an object of type Project.
  • The function itself has a Rustdoc comment that will be used to document this endpoint in the OpenAPI schema.

From this information, Dropshot can generate an OpenAPI specification for this API that describes the endpoint (which OpenAPI calls an "operation"), its documentation, the possible responses that it can return, and the schema for each type of response (which can also include documentation). This is largely known statically, though generated at runtime.

#[endpoint { ... }] attribute parameters

The endpoint attribute accepts parameters the affect the operation of the endpoint as well as metadata that appears in the OpenAPI description of it.

This example is not tested
#[endpoint {
    // Required fields
    method = { DELETE | GET | PATCH | POST | PUT },
    path = "/path/name/with/{named}/{variables}",

    // Optional fields
    tags = [ "all", "your", "OpenAPI", "tags" ],

This is where you specify the HTTP method and path (including path variables) for the API endpoint. These are used as part of endpoint registration and appear in the OpenAPI spec output.

The tags field is used to categorize API endpoints and only impacts the OpenAPI spec output.

Function parameters

In general, a handler function looks like this:

This example is not tested
async fn f(
     rqctx: Arc<RequestContext>,
     [query_params: Query<Q>,]
     [path_params: Path<P>,]
     [body_param: TypedBody<J>,]
) -> Result<HttpResponse*, HttpError>

Other than the RequestContext, parameters may appear in any order. The types Query, Path, and TypedBody are called Extractors because they cause information to be pulled out of the request and made available to the handler function.

  • Query<Q> extracts parameters from a query string, deserializing them into an instance of type Q. Q must implement serde::Deserialize and schemars::JsonSchema.
  • Path<P> extracts parameters from HTTP path, deserializing them into an instance of type P. P must implement serde::Deserialize and schemars::JsonSchema.
  • TypedBody<J> extracts content from the request body by parsing the body as JSON and deserializing it into an instance of type J. J must implement serde::Deserialize and schemars::JsonSchema.

If the handler takes a Query<Q>, Path<P>, or a TypedBody<J> and the corresponding extraction cannot be completed, the request fails with status code 400 and an error message reflecting a validation error.

As with any serde-deserializable type, you can make fields optional by having the corresponding property of the type be an Option. Here's an example of an endpoint that takes two arguments via query parameters: "limit", a required u32, and "marker", an optional string:

use http::StatusCode;
use dropshot::HttpError;
use dropshot::TypedBody;
use dropshot::Query;
use dropshot::RequestContext;
use hyper::Body;
use hyper::Response;
use schemars::JsonSchema;
use serde::Deserialize;
use std::sync::Arc;

#[derive(Deserialize, JsonSchema)]
struct MyQueryArgs {
    limit: u32,
    marker: Option<String>

async fn myapi_projects_get(
    _: Arc<RequestContext>,
    query: Query<MyQueryArgs>)
    -> Result<Response<Body>, HttpError>
    let query_args = query.into_inner();
    let limit: u32 = query_args.limit;
    let marker: Option<String> = query_args.marker;
        .body(format!("limit = {}, marker = {:?}\n", limit, marker).into())?)

Endpoint function return types

Endpoint handler functions are async, so they always return a Future. When we say "return type" below, we use that as shorthand for the output of the future.

An endpoint function must return a type that implements HttpResponse. Typically this should be a type that implements HttpTypedResponse (either one of the Dropshot-provided ones or one of your own creation).

The more specific a type returned by the handler function, the more can be validated at build-time, and the more specific an OpenAPI schema can be generated from the source code. For example, a POST to an endpoint "/projects" might return Result<HttpResponseCreated<Project>, HttpError>. As you might expect, on success, this turns into an HTTP 201 "Created" response whose body is constructed by serializing the Project. In this example, OpenAPI tooling can identify at build time that this function produces a 201 "Created" response on success with a body whose schema matches Project (which we already said implements Serialize), and there would be no way to violate this contract at runtime.

These are the implementations of HttpTypedResponse with their associated HTTP response code on the HTTP method:

Return TypeHTTP status code

In situations where the response schema is not fixed, the endpoint should return Response<Body>, which also implements HttpResponse. Note that the OpenAPI spec will not include any status code or type information in this case.

Support for paginated resources

"Pagination" here refers to the interface pattern where HTTP resources (or API endpoints) that provide a list of the items in a collection return a relatively small maximum number of items per request, often called a "page" of results. Each page includes some metadata that the client can use to make another request for the next page of results. The client can repeat this until they've gotten all the results. Limiting the number of results returned per request helps bound the resource utilization and time required for any request, which in turn facilities horizontal scalability, high availability, and protection against some denial of service attacks (intentional or otherwise). For more background, see the comments in dropshot/src/pagination.rs.

Pagination support in Dropshot implements this common pattern:

  • This server exposes an API endpoint that returns the items contained within a collection.
  • The client is not allowed to list the entire collection in one request. Instead, they list the collection using a sequence of requests to the one endpoint. We call this sequence of requests a scan of the collection, and we sometimes say that the client pages through the collection.
  • The initial request in the scan may specify the scan parameters, which typically specify how the results are to be sorted (i.e., by which field(s) and whether the sort is ascending or descending), any filters to apply, etc.
  • Each request returns a page of results at a time, along with a page token that's provided with the next request as a query parameter.
  • The scan parameters cannot change between requests that are part of the same scan.
  • With all requests: there's a default limit (e.g., 100 items returned at a time). Clients can request a higher limit using a query parameter (e.g., limit=1000). This limit is capped by a hard limit on the server. If the client asks for more than the hard limit, the server can use the hard limit or reject the request.

As an example, imagine that we have an API endpoint called "/animals". Each item returned is an Animal object that might look like this:

    "name": "aardvark",
    "class": "mammal",
    "max_weight": "80", /* kilograms, typical */

There are at least 1.5 million known species of animal -- too many to return in one API call! Our API supports paginating them by "name", which we'll say is a unique field in our data set.

The first request to the API fetches "/animals" (with no querystring parameters) and returns:

    "page_token": "abc123...",
    "items": [
            "name": "aardvark",
            "class": "mammal",
            "max_weight": "80",
            "name": "badger",
            "class": "mammal",
            "max_weight": "12",

The subsequent request to the API fetches "/animals?page_token=abc123...". The page token "abc123..." is an opaque token to the client, but typically encodes the scan parameters and the value of the last item seen ("name=badger"). The client knows it has completed the scan when it receives a response with no page_token in it.

Our API endpoint can also support scanning in reverse order. In this case, when the client makes the first request, it should fetch "/animals?sort=name-descending". Now the first result might be "zebra". Again, the page token must include the scan parameters so that in subsequent requests, the API endpoint knows that we're scanning backwards, not forwards, from the value we were given. It's not allowed to change directions or sort order in the middle of a scan. (You can always start a new scan, but you can't pick up from where you were in the previous scan.)

It's also possible to support sorting by multiple fields. For example, we could support sort=class-name, which we could define to mean that we'll sort the results first by the animal's class, then by name. Thus we'd get all the amphibians in sorted order, then all the mammals, then all the reptiles. The main requirement is that the combination of fields used for pagination must be unique. We cannot paginate by the animal's class alone. (To see why: there are over 6,000 mammals. If the page size is, say, 1000, then the page_token would say "mammal", but there's not enough information there to see where we are within the list of mammals. It doesn't matter whether there are 2 mammals or 6,000 because clients can limit the page size to just one item if they want and that ought to work.)

Dropshot interfaces for pagination

We can think of pagination in two parts: the input (handling the pagination query parameters) and the output (emitting a page of results, including the page token).

For input, a paginated API endpoint's handler function should accept a Query<PaginationParams<ScanParams, PageSelector>>, where ScanParams is a consumer-defined type specifying the parameters of the scan (typically including the sort fields, sort order, and filter options) and PageSelector is a consumer-defined type describing the page token. The PageSelector will be serialized to JSON and base64-encoded to construct the page token. This will be automatically parsed on the way back in.

For output, a paginated API endpoint's handler function can return Result<HttpResponseOk<ResultsPage<T>, HttpError> where T: Serialize is the item listed by the endpoint. You can also use your own structure that contains a ResultsPage (possibly using #[serde(flatten)]), if that's the behavior you want.

There are several complete, documented examples in the "examples" directory.

Advanced usage notes

It's possible to accept additional query parameters besides the pagination parameters by having your API endpoint handler function take two different arguments using Query, like this:

use dropshot::HttpError;
use dropshot::HttpResponseOk;
use dropshot::PaginationParams;
use dropshot::Query;
use dropshot::RequestContext;
use dropshot::ResultsPage;
use dropshot::endpoint;
use schemars::JsonSchema;
use serde::Deserialize;
use std::sync::Arc;
#[derive(Deserialize, JsonSchema)]
struct MyExtraQueryParams {
    do_extra_stuff: bool,

#[endpoint {
    method = GET,
    path = "/list_stuff"
async fn my_list_api(
    rqctx: Arc<RequestContext>,
    pag_params: Query<PaginationParams<MyScanParams, MyPageSelector>>,
    extra_params: Query<MyExtraQueryParams>,
) -> Result<HttpResponseOk<ResultsPage<String>>, HttpError>
 /* ... */

You might expect that instead of doing this, you could define your own structure that includes a PaginationParams using #[serde(flatten)], and this ought to work, but it currently doesn't due to serde_urlencoded#33, which is really serde#1183.



Automated testing facilities. These are intended for use both by this crate and dependents of this crate.



An ApiDescription represents the endpoints and handler functions in your API. Other metadata could also be provided here. This object can be used to generate an OpenAPI spec or to run an HTTP server implementing the API.


ApiEndpoint represents a single API endpoint associated with an ApiDescription. It has a handler, HTTP method (e.g. GET, POST), and a path-- provided explicitly--as well as parameters and a description which can be inferred from function parameter types and doc comments (respectively).


ApiEndpointParameter represents the discrete path and query parameters for a given API endpoint. These are typically derived from the members of stucts used as parameters to handler functions.


Metadata for an API endpoint response: type information and status code.


Configuration for a Dropshot server.


ScanParams for use with PaginationParams when the API endpoint has no scan parameters (i.e., it always iterates items in the collection in the same way).


HttpError represents an error generated as part of handling an API request. When these bubble up to the top of the request handling stack (which is most of the time that they're generated), these are turned into an HTTP response, which includes:


Body of an HTTP response for an HttpError. This type can be used to deserialize an HTTP response corresponding to an error in order to access the error code, message, etc.


HttpResponseAccepted<T: Serialize> wraps an object of any serializable type. It denotes an HTTP 202 "Accepted" response whose body is generated by serializing the object.


HttpResponseCreated<T: Serialize> wraps an object of any serializable type. It denotes an HTTP 201 "Created" response whose body is generated by serializing the object.


HttpResponseDeleted represents an HTTP 204 "No Content" response, intended for use when an API operation has successfully deleted an object.


HttpResponseOk<T: Serialize> wraps an object of any serializable type. It denotes an HTTP 200 "OK" response whose body is generated by serializing the object.


HttpResponseUpdatedNoContent represents an HTTP 204 "No Content" response, intended for use when an API operation has successfully updated an object and has nothing to return.


A thin wrapper around a Hyper Server object that exposes some interfaces that we find useful (e.g., close()). TODO-cleanup: this mechanism should probably do better with types. In particular, once you call run(), you shouldn't be able to call it again (i.e., it should consume self). But you should be able to close() it. Once you've called close(), you shouldn't be able to call it again.


The Request Method (VERB)


Querystring parameters provided by clients when scanning a paginated collection


Path<PathType> is an extractor used to deserialize an instance of PathType from an HTTP request's path parameters. PathType is any structure of yours that implements serde::Deserialize. See this module's documentation for more information.


Query<QueryType> is an extractor used to deserialize an instance of QueryType from an HTTP request's query string. QueryType is any structure of yours that implements serde::Deserialize. See this module's documentation for more information.


Handle for various interfaces useful during request processing.


A page of results from a paginated API


TypedBody<BodyType> is an extractor used to deserialize an instance of BodyType from an HTTP request body. BodyType is any structure of yours that implements serde::Deserialize. See this module's documentation for more information.



Represents the logging configuration for a server. This is expected to be a top-level block in a TOML config file, although that's not required.


Specifies the behavior when logging to a file that already exists.


Log messages have a level that's used for filtering in the usual way.


The order in which the client wants to page through the requested collection


Describes whether the client is beginning a new scan or resuming an existing one



MIME type for plain JSON data


MIME type for newline-delimited JSON data


header name for conveying request ids ("x-request-id")



Extractor defines an interface allowing a type to be constructed from a RequestContext. Unlike most traits, Extractor essentially defines only a constructor function, not instance functions.


HttpResponse must produce a Result<Response<Body>, HttpError> and generate the response metadata. Typically one should use Response<Body> or an implementation of HttpTypedResponse.

Attribute Macros


This attribute transforms a handler function into a Dropshot endpoint suitable to be used as a parameter to ApiDescription::register(). It encodes information relevant to the operation of an API endpoint beyond what is expressed by the parameter and return types of a handler function.