No Clocks

This approach of defining tiny schemas, such as the chainLinkContentField, is a useful design pattern for keeping API definitions DRY. This is analogous to creating small, atomic, highly reusable functions in a programming language, rather than long, complex single-purpose functions. If you find yourself repeating a property definition across multiple schemas, consider lifting that property into its own field definition schema. If there are groups of related properties that you use together in multiple schemas, you can group them together into a reusable {group}Fields schema (with a descriptive schema name that indicates its purpose, such as mutableChainLinkFields), then mix them into other schemas using the allOf schema composition construct. This practice is one form of refactoring that is useful when defining and refining schemas.

Composition is not Inheritance

Warning: this JSON Schema composition construct is not inheritance… even if some tools translate this into inheritance in a target language. This means that, as the “allOf” name implies, all the schema constraints apply: you cannot override or replace constraints.

authorId: description: >- The ID of the author resource: who created this chain link. type: string minLength: 4 maxLength: 48 pattern: ^[-_a-zA-Z0-9:+$]{4,48}$ readOnly: true

Suppose we want to use schema composition but loosen those constraints in the chainLink schema’s authorId to allow 2 to 64 characters, we can express this as follows:

chainLink: title: A Chain Link allOf: - $ref: '#/components/schemas/chainLinkItem' - type: object properties: authorId: description: >- The ID of the author resource: who created this chain link. type: string minLength: 2 maxLength: 64 pattern: ^[-_a-zA-Z0-9:+$]{2,64}$ readOnly: false

However, we won’t get the desired effect. While the code generation may not change, the schema validation of a JSON object containing an authorId still enforces all of the subschema constraints. Thus, the effective schema constraints for the authorId property are the union of all the constraints: type: string minLength: 4 maxLength: 48 pattern: ^[-_a-zA-Z0-9:+$]{4,48}$ type: string minLength: 2 maxLength: 64 pattern: ^[-_a-zA-Z0-9:+$]{2,64}$

While a value such as “C289D6F7-6B30-4788-9C70-4274730FAFCA” satisfies all 8 of these constraints, a shorter author ID string of 3 characters, “A00”, will fail the constraint #2 and #4, and thus that JSON would be rejected.

A final note on schema composition. The behavior of the allOf construct is well defined within JSON Schema for JSON validation. However, there is no standard for how this JSON schema construct must be treated in other tools such as code generation for client or server SDKs. Thus, each tool vendor (SmartBear’s swagger-codegen, the OSS openapi-generator, ApiMatic, Speakeasy, Fern, Kiota, etc.) may interpret JSON Schema in individual and different ways. It is useful to try them out to see if their interpretation and implementation meets your needs and expectations.

JSON Schema provides other keywords for schema composition (the oneOf, anyOf, and not keywords, as well as conditionals with a if/then/else construct) but these are more advanced topics and I’ve already asked too much of you to read this far. Stay tuned, however, there is more to come!

A promise of REST APIs is good decoupling of clients and services. This is achieved in part by reducing business logic as much as possible in the client application. For example, a client application may use a form for collecting information used in a POST operation to create an API resource, or to edit an existing resource before updating it with a PUT or PATCH operations. The client then maps the form fields to the properties of the operation’s request body. Clients can use front end frameworks and libraries to perform lots of low-level validation in the front end corresponding to JSON schema constraints

Forms which use required data fields for properties that are required in the JSON schema using date pickers checkboxes for selecting Boolean true or false values drop down lists that allows selection from a list of fixed enum values constrained numeric text entry form fields that enforce a regular expression from a pattern constraint

However, this only covers “syntactic” or static field-level validation. Often, an API will also have business rules that the client must follow. Secure API services will enforce those business rules in the API operations

Parse the options and (JSON) request body and return a 400 Bad Request if any of the request data is malformed (i.e. does not satisfy the constraints of the operation (such as required body or required parameters) or all the JSON Schemas associated with the operation’s parameters or request body) Verify that the caller passes valid Authorization to the API call, and return 401 Unauthorized if not Verify that the caller is authorized to perform the API operation, and return a 403 Forbidden error if not. Verify the state of the application and return 409 Conflict if the operation would put the application into an inconsistent state Verify the semantics of the request body and return a 422 Unprocessable Content error if the request is incomplete, inconsistent, or otherwise invalid

One way to implement a dry run is to create a separate "validation” operation for each API operation. This has the significant disadvantage of greatly increasing the footprint (size) of the API and adding a lot of duplication.

Rather than duplicate operations to add sibling validation operations, another approach is to add a ?dryRun=true query parameter to the operations. When used, the operation can return 204 No Content if the request contains no problems. The dryRun parameter acts as a “short circuit” in the API operation. The implementation performs the full validation it would normally do before executing the desired behavior, but then stops before actually executing anything other than the validation.

This pattern has a small impact on the API footprint compared to making sibling validation operations. A smaller footprint makes the API easier to read and understand. It is also a good use of the DRY principal, since you do not have to duplicate the definition of all the operation request parameters and request bodies, which opens up the chance for them to become out of sync.

Deeply nested schemas can become unwieldy and hard to maintain. For instance, a User object containing an Address object, which in turn contains a Location object, can quickly become complex. Why it matters: Simplifying schemas enhances readability and maintainability, making it easier for both developers and consumers to understand and work with the API.

Defining schemas, parameters, and responses inline repeatedly instead of using the components section leads to redundancy and potential inconsistencies. Why it matters: Leveraging components promotes reusability and consistency across the API specification.

Logically group your APIs into smaller, domain-specific specs — like auth.yaml, payment.yaml, orders.yaml. Use tags in OpenAPI to group related endpoints (like Order, Customer, Admin) even within a single file if needed.

/openapi ├── auth.yaml ├── customer.yaml ├── orders.yaml └── components/ └── common-schemas.yaml

401 Unauthorized vs 403 Forbidden

In web development, ensuring access control is essential in safely and efficiently managing APIs. The meanings of 401 Unauthorized and 403 Forbidden are sometimes confused. Nonetheless, both codes have to do with restricted resources, but they serve different purposes. In this article, we will explain the codes and instruct you on which one to use.

401 Unauthorized?​ The response is an HTTP error code for a request lacking valid authentication credentials from a client is referred to as the 401 Unauthorized status code. That being said, it means that before accessing the requested resource, it’s necessary for the server to authenticate itself to the client. If no credentials are provided or if wrong ones are given by the client, then what follows is a 401 status code.

When to Use 401 Unauthorized​ Use 401 Unauthorized when: No authentication details have been received yet from the client. The authentication information supplied – username and password/token – is not valid/has expired. There is no authorization header present in your requests like “Authorization.” For instance, if an API demands Bearer token for access but this token has not been included in any request or is incorrect it will issue back a response having HTTP status code 401 Unauthorized (the most common case).

403 Forbidden?​ The reason for using a 403 Forbidden status code is when the server recognizes the request, the client has been authenticated, but the client does not have permission to access the requested resource. It means that in this case, a client is known while a server intentionally turns down fulfilling the request because of inadequate privileges. When to Use 403 Forbidden​ Use 403 Forbidden when: Authenticated clientele lack sufficient permissions to reach given resources. Server denies resource access irrespective of client’s authentication state. Client’s access to resources is prohibited by any form of an access control system. For instance, an authorized user may try accessing an admin only page without having adequate role. Even if one gets logged in, the response will indicate 403 Forbidden if they do not have sufficient rights.