4.2 KiB
Shared Parameters and Responses
While designing API's in Stoplight, it is common to have multiple endpoints share a common set of query parameters and API responses. To help reduce extra work (and the chance of introducing errors), it is important to:
- Identify endpoints with common parameters
- Use shared properties to reference the same property multiple times instead of rewriting the properties for each individual endpoint.
Shared properties in Stoplight come in two forms:
-
Parameters - These are shared parameters that can be applied to requests across multiple endpoints.
-
Responses - These are shared responses that apply the same response object to multiple endpoints.
Parameters
Shared parameters provide a way to re-use request properties across multiple API endpoints without having to duplicate effort.
Shared parameters can be used as the following request properties:
- path - Specifies that the shared parameter can only be used in an API endpoint as a URL path
- query - Specifies that the shared parameter can only be used in an API endpoint as an URL query string
- header - Specifies that the shared parameter can only be used in an API endpoint as a HTTP Header field object
- body - Specifies that the shared parameter can only be used in an API endpoint as a HTTP message body
- form-data - Specifies that the shared parameter can only be used in an
API endpoint as a HTTP body in the
multipart/form-dataformat
Similar to generic request parameters, restrictions on the parameter values can also be applied based on type, expected default value, minimum/maximum length, and regular expression (regex).
To use a shared parameter, navigate to an API endpoint's Request section and create a reference to the shared parameter using the "chain" button as shown in the image above. Once the parameter has been referenced, any updates to the shared parameter will automatically be propagated to every endpoint using that parameter.
Like other references in Stoplight, shared parameters can also be shared across files, projects, and other external sources.
Shared Responses
Shared responses provide a way to re-use response objects across multiple API endpoints without having to duplicate effort. Similar to shared properties discussed above, shared responses allow you to reference a single response multiple times without having to recreate each response manually. The added benefit of this approach is that updates to the shared response object are automatically propagated to any endpoint using that object, no extra changes required.
Shared responses allow you to configure the following properties:
- Headers - Customize the HTTP Headers returned in the response
- Response body - Customize the HTTP message body contents using the Stoplight modeling tool (or reference a pre-existing model)
To use a shared response, navigate to an API endpoint's Response section and create a reference to the shared response by choosing the Type of the response as "Reference". Once the Response type is set to "Reference", you can then choose the shared response to use for that endpoint. Shared responses can also be shared across files, projects, and other external sources.
Related