API Guidelines - Lucca API

Get Started

Motivation

The goal of this document is to facilitate the work and minimize the effort of all API users at Lucca while protecting their investment and encouraging API adoption. These guidelines lay down the foundation for collaboration, stability, and extensibility.

Content

This API guideline contains:

General guidelines in regard to APIs building and modeling, especially public APIs.
Guidelines in regard to generating events from the state of API resources.
A Spectral ruleset that aims at helping you implement these API guidelines in your projects.

How to read these guidelines

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Rules are numbered, and this numbering system is also referenced in the spectral ruleset.
Whenever there are two key words for a given rule, then the strictest is aimed at the Lucca API, and the more lenient, to private internal APIs.
Whenever a rule only affects the Lucca API (public), then it is prefixed with [LUCCA API].

Validating your API specs

In order to validate your OpenAPI specs with the guidelines, you may:

Make sure your OpenAPI specs is v3.x.

The spectral ruleset only supports OAS v3.x, ideally ^3.1.x

Install stoplight/spectral

npm install -g @stoplight/spectral

Install Lucca API guidelines through npm

npm install @lucca/api-guidelines-spectral

Lint your oas file with the spectral ruleset of this project

spectral lint <oas-file> -r <lucca-api-guidelines-folder>/.spectral.yaml

Lucca API building principles

Required Qualities

Lucca initially started as a software company that developed a single app. However, due to the founder’s seemingly insatiable appetite, many complementary apps were subsequently developed. The proliferation of apps posed two significant challenges to the platform architecture:

Mitigate the risk of tight coupling between applications, which would make the entire system impossible to evolve and maintain.
Avoid duplication and redundancy by rigorously segregating responsibilities between applications and laying out a common central to manage the remaining shared components.

Consequently, the platform MUST:

Offer simplicity thanks to a modular and unified interface for hosted applications that acts as an abstraction layer defining a shared representation of an enterprise objects and processes (also called “the metamodel”, which is an enterprise ontology) and the means to interact with the state of this model.
Be highly available and resilient: no single component’s fault should shut down the entire system (i.e., no SPOF).
Be extensible: it can welcome any new application, regardless of its origin, by making integration painless. New features can be added at a very low cost.
Scale well with users expansions, without degrading performance nor profitability.

Availability is considered more important than consistency. The platform embraces eventual consistency, while being fully aware of the potential cost in terms of cognitive complexity for users and developers. Simplicity through uniformity is considered more important than performance.

Top-Level Principles

As a result, here are the principles behind the Lucca API design:

All cross-applications interactions MUST go through an asynchronous, uniform, stateless, resource-oriented, extensible, web interface (WOA: Web-Oriented Architecture) when available - which is the Lucca API.
1. Corollary 1.1.: The Lucca API MUST conform to the Lucca current API standard (as of now: v4).
2. Corollary 1.2.: All interactions MUST share a common protocol (HTTP) and message format (JSON).
3. Corollary 1.3.: The enterprise model (ie the namespace) MUST pursue simplicity and universality. In particular, the enterprise model MUST adopt an atomic design methodology (primitives & composites in the Zachman framework) and strive to adopt narrow functional boundaries (conform to the Zachman framework interrogatives).
4. Corollary 1.4.: An application MUST not fail if another application is down.
5. Corollary 1.5.: Any event system (webhooks) MUST be stateless and resource-oriented.
6. Corollary 1.6.: Any application MAY freely extend the enterprise model.
The Lucca API MUST be agnostic to the actual applications providing concrete implementations for a subset of the enterprise model.
1. Corollary 2.1.: The Lucca API MUST have full control over the enterprise model (ie the namespace).
2. Corollary 2.2: Third-party app integration possibilities MUST be strictly equal to those of first-party apps. Anything a first-party app can do in the platform, a third-party app should be able to do. From the end-user point of view, it must be indistinguishable as long as the app developer seriously invested in the integration.
3. Corollary 2.3: The Lucca API MUST have no opinion over the actual implementation details made by applications, as long as the interface contract with the Lucca API is respected.
The Lucca API MUST strive to become irresistible by investing heavily in the developer experience.
1. Corollary 3.1.: The Lucca API MUST have proper change management and offer long-term support.
2. Corollary 3.2.: The documentation MUST be human-readable, complete, and illustrated.
3. Corollary 3.3.: SDKs SHOULD be published to reduce the workload of developers.

General Rules

[001] MUST be RESTful

All APIs MUST be RESTful and JSON-based (charset = UTF-8). RESTful APIs tend to be less use-case specific and come with less rigid client / server coupling. Regarding the REST constraints, all APIs MUST at least be at level 2 in Richardson’s maturity model. Some level 3 (i.e. HATEOAS) features MAY be implemented, but we do not consider it a requirement. In the Lucca API, two features are implemented:

embeddings of related resources representations through a standardized format.
links to related resources, which may help clients predict access control as well as expected inputs.

[002] SHOULD embrace a design first approach

In a nutshell, the Design First principle means:

Define the API first, before coding its implementation, using a standard specification language (we highly recommend OpenAPI) ;
Get early review feedback from peers and client developers ; and iterate from there.
Then, implement the API in conformance to the definition.
Ideally, continuous integration checks for discrepancies between the design definition and the actual implementation.

Defining APIs first outside the code aims at facilitating early review feedback and favoring:

profound understanding of the domain and required functionality.
generalized business entities / resources, i.e. avoidance of use case specific APIs.
clear separation of WHAT vs. HOW concerns, i.e. abstraction from implementation aspects — APIs should be stable even if we replace complete service implementation including its underlying technology stack.

Moreover, defining an API with a standardized specification format also facilitates:

having a single source of truth for the API specification; it is a crucial part of a contract between service provider and client users
infrastructure tooling for API discovery, API GUIs, API documents, automated quality checks.

[003] SHOULD be robust

Robustness Principle (Postel’s law) “Be tolerant of inputs and strict on outputs”. In other words, enforce strict validation on responses, but be more lenient on requests. Have fail-safe defaults. The degree of leniency may be negotiated with the client through the Prefer HTTP header.

[004] SHOULD NOT surprise clients

Principle of Least Surprise People are part of the system. Choose interfaces that match the user’s experience, expectations, and mental models. Avoid unexpected side-effects and black-box effects. Conform to standards and enforce consistency and uniformity.

[005] SHOULD always be explicit

Document the assumptions behind the design so that when the time comes to change it you can more easily figure out what else has to change. Expect not only to modify and replace modules, but also to remodularize as the system and its requirements become better understood.

[006] SHOULD embrace an collaborative and iterative design process

You won’t get it right the first time, so make it easy to change. Do not try to anticipate future changes, you’ll mostly miss the mark. Take time to refactor existing components whenever the system changes. Besides, let anyone comment on the design; you need all the help you can get. Eventually, kill rarely used components: deterioration and corruption accumulate unnoticed.

[007] SHOULD define useful resources

As a rule of thumb resources should be defined to cover 90% of all its client’s use cases. A useful resource should contain as much information as necessary, but as little as possible. A great way to support the last 10% is to allow clients to specify their needs for more/less information by supporting filtering and embedding. You SHOULD avoid excessive generality when modeling resources: if it is good for everything, then it is good for nothing.

[008] MUST secure your API

Check every operation for authenticity (who), integrity (what), and authorization (can).

[009] MUST be transparent regarding access rights

Document all access rights that may not be immediately understood ; all the more so if this affects data that could be considered sensitive. For example: granting someone the right to create leaves for another employee may reveal this employee’s work-contract dates if errors are thrown when attempting to create leaves outside the contract date range.

Endpoints

[100] MUST use kebab-case for paths naming

GET /lucca-api/leave-requests HTTPS/1.1
GET /lucca-api/time-entries HTTPS/1.1
...

[101] SHOULD use paths that conform to resources names

Paths SHOULD stick to the plural form of the name of the type of resource when not a singleton resource. In practice, when the resource is listed in a collection, then the path should be equal to the type of the collection representation.

GET /leave-requests HTTPS/2
{
    "type": "leave-requests",
    "items": []
}

[102] MUST conform to HTTP methods standard semantics

Be compliant with the standardized HTTP semantics (refer to RFC-9110).

GET requests are used to read either a single or a collection of resource(s) representation(s).

PUT requests are used to update - or create if it does not already exist - entire resources.

POST requests are usually used to create single resources on a collection resource endpoint, but may also be used to execute commands on single resources endpoint.

PATCH method extends HTTP to update parts of the resource representation

DELETE requests are used to delete resources.

HEAD requests are used to retrieve the header information of single resources and resource collections.

Glossary: safe, idempotent, cacheable

If an idempotent implementation of an HTTP method that is not supposed to be idempotent is required, then please consider using the Idempotency-Key HTTP header (c.f. RFC).

[103] MUST avoid having verbs in URLs

The API describes resources, so the only place where actions should appear is in the HTTP methods. In URLs, use only nouns and avoid verbs.

[104] SHOULD NOT show structural relationships in URIs

Showing structural relationships in URIs can be a good way of revealing dependencies and/or access rights scoping. Nonetheless, it also:

limits emergent uses, as it forces clients to iterate per parent resource.
forces clients to know the parent resource id to GET the child.
present the risk of having two URIs referencing the same collection resource (/parents/children vs parents/:id/children).
can lead to pathing ambiguity (/parents/children vs /parents/:id)

If you choose nonetheless to have sub-resources, then you SHOULD avoid having more than 3 levels of depth. Going deeper increases complexity as well as URL length (bear in mind some web browsers truncate URLs over 2,000 characters).

[105] SHOULD avoid pathing ambiguity

Pathing ambiguity naturally emerges from nested URL resources:

GET /employees/416 HTTPS/2
> Here, second URL segment is an ID.

GET /employees/addresses HTTPS/2
> Here, second URL segment is a child resource type.

[106] MUST use official HTTP status codes

You must only use official HTTP status codes consistently with their intended semantics. Official HTTP status codes are defined via RFC standards and registered in the IANA Status Code Registry.

[107] SHOULD only use most common HTTP status codes

Code	Methods	MUST document?	RFC	Description
200 OK	all	✅	rfc9110	General success response. Prefer a more specific success code when possible.
201 Created	POST, PUT	✅	rfc9110	Returned on successful resource creation, even if response body is empty. Used along the Location header when the created resource URI is indeterminate for clients.
202 Accepted	POST, PUT, PATCH, DELETE	✅	rfc9110	The request was successful and will be processed asynchronously. Only applicable to methods which change the state on the server side.
204 No Content	PUT, PATCH, DELETE	✅	rfc9110	Returned in place of a 200 if no response body is returned. Only applicable to methods which change the state of the resource.
304 Not Modified	GET, HEAD	✅	rfc9110	Returned whenever a conditional GET or HEAD request would have resulted in 200 response if the condition evaluated to false Usually: the resource has not been modified since the version passed via request headers If-Modified-Since or If-None-Match. For PUT, PATCH or DELETE requests, use 412 instead.
400 Bad Request	all	✅	rfc9110	Unspecific client error indicating that the server cannot process the request due to something that is perceived to be a client error (e.g. malformed request syntax, invalid request). Should also be delivered in case of input body fails business logic / semantic validation (instead of using 422).
401 Unauthorized	all	❌	rfc9110	Actually “Unauthenticated”. The credentials are missing or not valid for the target resource. For an API, this usually means that the provided token or cookie is not valid. As this can happen for almost every endpoint, APIs should normally not document this.
403 Forbidden	all	❌	rfc9110	The user is not authorized to change this resource. For an API, this can mean that the request’s token was valid, but was missing a scope for this endpoint. Or that some object-specific authorization failed. We recommend only documenting the second case.
404 Not Found	all	❌	rfc9110	The target resource was not found, either because it does not exist, or because the user cannot access it. This will be returned by most (not documented) paths on most APIs. For a PUT endpoint that does not support creation (only updates), then this might be returned if the resource does not exist. Apart from these special cases, this does not need to be documented. You should not return a 404 on a DELETE request on a resource that does not exist (or was already deleted), but a 204. You may return a 404 on write requests whenever the resource references another resource that is not accessible or does not exist.
405 Method Not Allowed	all	✅	rfc9110	The request method is not supported for this resource. Using this response code on a documented endpoint only makes sense if it depends on some internal resource state whether a specific method is allowed. Do not use it unless you have such a special use case, but then make sure to document it, making it clear why a resource might not support a method.
406 Not Acceptable	all	❌	rfc9110	Resource only supports generating content with content-types that are not listed in the Accept header sent in the request.
409 Conflict	POST, PUT, PATCH, DELETE	✅	rfc9110	The request cannot be completed due to conflict with the current state of the target resource. For example, you may get a 409response when updating a resource that is older than the existing one on the server, resulting in a version control conflict. If this is used, it MUST be documented. For successful robust creation of resources (PUT or POST) you should always return 200 or 204 and not 409, even if the resource exists already. If any If-* conditional headers cause a conflict, you should use 412 and not 409. Only applicable to methods which change something.
410 Gone	all	❌	rfc9110	The resource does not exist any longer (but did exist in the past), and will most likely not exist in the future. This can be used e.g. when accessing a resource that has intentionally been deleted. This normally does not need to be documented, unless there is a specific need to distinguish this case from the normal 404
411 Length Required	POST, PUT, PATCH	✅	rfc9110	The server requires a Content-Length header for this request. This is normally only relevant for large media uploads. The corresponding header parameter should be marked as required. If used, it MUST to be documented (and explained). Only applicable for methods with a request body.
412 Precondition Failed	PUT, PATCH, DELETE	❌	rfc9110	Returned for conditional requests (If-Match and If-None-Match) if the condition failed. Used for optimistic locking. Normally only applicable to methods that change something. For HEAD or GET requests, use 304 instead.
415 Unsupported Media Type	POST, PUT, PATCH	❌	rfc9110	The client did not provide a supported Content-Type for the request body. Only applicable to methods with a request body.
423 Locked	PUT, PATCH, DELETE	✅	rfc4918	Used for pessimistic locking.
428 Precondition Required	all	❌	rfc6585	Server requires the request to be conditional (If-Match and If-None-Match headers). Instead of documenting this response status, the required headers should be documented and marked as required.
429 Too Many Requests	all	❌	rfc6585	The client is not abiding by the rate limits in place and has sent too many requests.
500 Internal Server Error	all	❌	rfc9110	A generic error indication for an unexpected server execution problem.
501 Not Implemented	all	❌	rfc9110	Server cannot fulfill the request (usually implies future availability, e.g. new feature).
503 Service Unavailable	all	❌	rfc9110	Service is temporarily down. Ideally, also return a Retry-After header giving clients the time to wait before retrying.

[108] MUST return a Problem for 4xx and 5xx responses

Problem JSON is a standard way of describing errors. It is defined in the RFC 9457. It provides extensible human and machine readable failure information, beyond the HTTP response status code. All 4xx and 5xx status codes MUST respond with a Problem JSON. The Problem JSON object MUST be served with the content-type application/problem+json.

[109] [LUCCA-API] MUST indicate x-provider in the spec for each path

The x-provider OpenAPI extension is used to indicate which application offers concrete implementation for the given endpoint. It makes it possible to bundle an application specification, with only their own subset of operations.

paths:
    '/lucca-api/employees':
        x-provider: employee-directory

[110] [LUCCA-API] MUST use kebab-case for operationId in the OpenAPI spec for each endpoint

paths:
    '/lucca-api/employees':
        get:
            operationId: list-employees

[111] SHOULD avoid custom media types

Stick to standards, like application/json, application/problem+json, application/hal+json, etc… You should avoid using custom media types like application/com.luccasoftware.leave+json. Custom media types beginning with x bring no advantage compared to the standard media type for JSON, and make automated processing more difficult.

[112] MUST be robust against excessive slashes

All services must normalize request paths before processing by removing duplicate and trailing slashes. Hence, all these requests must resolve to the same resource:

GET /employees//12 HTTPS/2
GET /employees/12/ HTTPS/2
GET /employees/12 HTTPS/2

[113] SHOULD avoid polymorphic endpoints

Polymorphic endpoints are harder to document, understand and use (both in reads and writes). So you should avoid implementing such an endpoint unless the different sub-types are very similar and/or there are so many sub-types that implementing a new endpoint for each would make the documentation harder to read. If you choose to implement a polymorphic endpoint, please refer to the OpenAPI spec in order to properly document it.

You then MUST document the discriminator.

In the context of the Lucca API, the discriminator MUST be the reserved type property (if the root resource is polymorphic, not a sub-object).

Schemas

[200] MUST support the (Internet) JSON format

Use Internet JSON (RFC 7493) to represent resource representations passed with HTTP in requests as well as responses bodies. As a consequence, any JSON payload MUST:

use UTF-8 encoding
consist of valid Unicode strings, i.e. must not contain non-characters or surrogates, and
contain only unique member names (no duplicate names).

[201] MUST return JSON objects as top-level data structures

In a response body, you must always return a JSON object as a top level data structure to support future extensibility (through adding additional properties).

[202] MUST name resources properties in camelCase

Why? Because we need to enforce consistent casing. We choose CamelCase to be consistent with the JavaScript syntax (JSON stands for JavaScript Object Notation).

	{
		"startsOn": "2023-01-01",
		"endsOn": "2023-01-31",
		"leaveAccount": { ... }
	}

[203] MUST conform to semantics of reserved property names

Some resource representation properties are reserved and as such MUST NOT be used in any other way:

Property name	Type	Semantics
id	string	null	Unique identifier of the resource in its collection.
type	string<enum>	Name of the type of the resource. Should be equal to the name of its JSON schema in the spec. Used as the discriminator of a polymorphic resource.
url	string<uri>	Absolute URL to the resource.
totalCount	integer<int32>	null	Counts all items of a collection (i.e. across all pages) that match the query parameters.
items	array (not nullable, but may be empty)	Lists the representations of all ressources in the collection page.
embedded	object	Lists representations of related resources.
links	object	Lists relationships with other resources which are not structural (i.e. not already present as reference properties of the target resource).

[204] SHOULD conform to type-dependent suffixes or prefixes

Properties of certain types SHOULD be named with a certain prefix or suffix to further indicate their type:

Type	Prefix	Suffix
`string<date>`	N/A	On
`string<date-time>`	N/A	At
`boolean`	“is”, ”has“, “can”…	N/A

Regarding booleans: do name boolean properties with an affirmative phrase (canDo instead of cantDo) in order to avoid double negations ; and prefix them with is, can, or has whenever it adds value.

[205] MUST declare enum values as upper-snake case strings

Enumerations should be represented as string typed OpenAPI definitions of request parameters or schemas properties. Enum values (declared either via enum or x-extensible-enum) need to consistently use the upper-snake case format, e.g. VALUE or YET_ANOTHER_VALUE. This is in order to better discriminate them from other properties.

[206] MUST define a format for number and integer types

Please refer to the OpenAPI spec for available formats. This is enforced in order to prevent clients from guessing the precision incorrectly, and thereby changing the value unintentionally.

[207] SHOULD define a minimum and maximum value for number and integer types

[208] MUST use standard formats for date and time properties

You MUST use the string typed formats date, date-time, time, duration, or period for the definition of date and time properties. The formats are based on the standard RFC 3339 internet profile (a subset of ISO 8601).

[209] SHOULD use standard formats for time duration and interval properties

Properties that represent durations and time intervals SHOULD be represented as strings formatted as defined by ISO 8601 (RFC 3339). Please note that Extended Date/Time Format (EDTF) defines an extension to express open ended time intervals that could be very convenient in query parameters filtering.

[210] SHOULD enforce strong validation over types Date(Only), DateTime (floating) and DateTimeOffset.

This is in order to avoid weird behaviors due to fallbacks (particularly on the server’s timezone).

If the API expects a DateTimeOffset, then clients MUST send the offset. Otherwise, return a Problem.
If the API expects a Date(Only), then clients MUST not send a time component (nor an offset, even though it’s valid). Otherwise, return a Problem.
You CANNOT compare a DateTime and a DateTimeOffset. Otherwise, return a Problem.

[211] MUST use standard formats for country, language and currency properties

Type	Standard	Description
Country	https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3	Three letters country code.
Language	https://www.rfc-editor.org/rfc/rfc4646.html	Language tag.
Currency	https://en.wikipedia.org/wiki/ISO_4217	Three letters currency code.

[212] SHOULD / MUST type ids as strings

Always use string rather than number type for identifiers in the Web layer, as it gives you more flexibility to evolve the identifier naming scheme. Be aware that monotonically increasing numeric identifiers may reveal confidential information to non-privileged clients. In which case you may consider random generators.

[213] SHOULD avoid using UUID

UUIDs may solve common issues:

Scaling problem in high frequency and near real-time use cases by making distribution easier.
Idempotent creation by letting clients write IDs.

But they have major drawbacks:

they do not convey any meaning
they are harder to memorize
they may make debugging harder
they have a higher memory and bandwidth footprint
they may be inefficient at the database level, especially when used as primary keys of highly referenced resources.
they are unordered along their creation history

[214] MAY consider giving clients control over ids

Advantages:

idempotent creation “by design”.
reduces the risk of concurrency and “lost updates” problems.
eases the synchronization between two systems by sharing ids, and as such, not needing to implement a mapping table.
may make IDs easier to understand and memorize on the client’s side.

In which case, creation SHOULD be handled through a PUT request.

PUT /api/users/jdoe HTTPS/1.1
{ ... }

[215] SHOULD avoid nullable array properties

Empty array values can unambiguously be represented as the empty list, i.e. [].

[216] MUST avoid nullable boolean properties

A boolean is essentially a closed enumeration of two values, true and false. If the content has a meaningful null value, then we recommend replacing the boolean with enumeration of named values or statuses (e.g. “yes”, “no”, “undefined”).

[217] MUST consider null and absent properties as the same

OpenAPI makes it possible to mark a property as nullable (oas2: nullable: true ; oas3: type: ['null', …]) or non required (through the required property of an object). A non-required property may be absent from the body. A nullable property may be null. In other words, we could make a distinction between the two cases. But we decided against. You MUST consider that an absent property is equivalent to declaring it null.

[218] SHOULD / MUST serialize null properties in responses

Even though an absent property is equivalent to it being null, we recommend avoiding elastic schema definitions. Always serializing all properties makes de-serializing easier in many languages and libraries.

[230] MUST use the common Money object

When describing an amount of money, then you must use the common Money object.

title: money
type: object
required:
    - amount
    - currency
properties:
    amount:
        type: number
        format: decimal
        multipleOf: 0.0001
        example: 9.95
    currency:
        type: string
        description: 3 letter currency code as defined by ISO-4217
        format: 'iso-4217'
        examples: ['USD', 'EUR', 'CAD']

You MUST NOT use this schema for inheritance. Treat it as a closed data type. You SHOULD $ref to this schema in your OpenAPI spec.

[231] MUST use the common WorkEventDuration object

When describing the duration of a work-related event of an employee (e.g. a shift, a leave, etc…), then you must use the common WorkEventDuration object. This gives you the ability to distinguish between two units: days and hours. Events in “days” unit have a duration defined as a fraction of a day of work (0.5 days might be 3.5 hours for an employee working 7h/day, and 4 hours for an employee working 8h/day). Having a common definition grants us the ability to aggregate all work-related events of an employee and make calculations.

title: WorkEventDuration
type: object
required:
    - iso
    - unit
properties:
    iso:
        type: string
        format: duration
        description: > 
            Duration as defined in RFC 3339 internet profile 
            (subset of ISO 8601)
    value:
        type: number
        format: float
        multipleOf: 0.001
    unit:
        type: string
        enum:
            - DAYS
            - HOURS
        x-enumDescriptions:
            DAYS: >
                The work event duration should be interpreted 
                as a fraction of a work day.
            HOURS: >
                The work event duration should be interpreted 
                as a number of hours, minutes, seconds.
examples:
    35h:
        iso: P1DT11H
        value: 35
        unit: HOURS
    218d:
        iso: P218D
        value: 218
        unit: DAYS
    negative:
        iso: -PT10H30M
        value: -10.5
        unit: HOURS

You MUST NOT use this schema for inheritance. Treat it as a closed data type. You SHOULD $ref to this schema in your OpenAPI spec. You SHOULD only support write requests on the iso property.

[240] MUST use Problem schema for error responses

Problem:
type: object
properties:
    type:
    type: string
    description: >
                A URI reference that identifies the problem type, ideally in the	context 
                of the Lucca API.
                **SHOULD** be an absolute URL to a page describing the nature of a problem.
                **MAY** be a relative URI
            default: about:blank
    examples:
                - "https://developers.luccasoftware.com/lucca-api/problems/not-found"
                - "https://tools.ietf.org/html/rfc7231#section-6.5.4"
    title:
    type: string
    description: >
        A short summary of the problem type. Written in US-English and readable
        by anyone tech-savvy. As such, **MAY** not be suited for non technical 
        stakeholders and not localized in the user's language.
    example: The expense was not found.
    status:
    type: integer
    format: int32
    description: >
        The HTTP status code generated by the origin server for this occurrence
        of the problem.
    minimum: 100
    maximum: 600
    exclusiveMaximum: true
    detail:
    type: string
    description: >
        A human readable explanation specific to this occurrence of the
        problem that is helpful to locate the problem and give advice on how
        to fix it. Written in US-English and readable by ayone tech-savvy, 
        **MAY** not be suited for non technical stakeholders and **MAY** not 
        be localized in the user's language.
    example: > 
                The expense #123 was not found on this server. You may double check 
                the given id or make sure you have access to it.
        errors:
            type: object
            description: >
                Lists all parameters or fields that violated validation rules.
                For each member, gives a list of human readable explaining the
                violation. Written in US-English and readable by anyone tech-savvy,
                **MAY** not be suited for non technical stakeholders and **MAY** not
                be localized in the user's language.
            additionalProperties:
                type: array
                items:
                    type: string
            examples:
                - limit:
                        - "The limit query parameter cannot exceed max value of 1000"

[250] [LUCCA-API] MUST conform to the Event schema for (webhook) events

...

[251] [LUCCA-API] MUST follow naming convention for event topics

Query Parameters

[301] MUST not deviate from reserved query parameters intended semantic

Some query parameters are reserved and as such MUST NOT be used in any other way:

Name	Type	Semantics
`page`	`string`	Cursor to the page.
`limit`	`integer<int32>`	Number of items per page.
`include`	`Array<string<‘embedded’ \| ‘links’ \| ‘totalItems’>>`	Control over the inclusion of embedded resource, the total count of a collection items and/or links to related resources.
`sort`	`Array<string<enum>>`	Control over the sorting of a collection’s items.

Outside of the Lucca API, the page parameter MAY be an integer (offset-based pagination) rather than a cursor.

[310] MUST define a default sorting strategy for consistency

This default sorting strategy should apply to a unique property. For this reason, it is recommended to sort on the reserved id property by default.

[311] MAY give clients control over the ordering of a collection’s items

Giving clients control over the ordering of items of a collection is considered good practice and can ease emergent uses.

[312] MUST conform to the standard when giving clients control over sorting

Sorting is handled through a sort query parameter whose BNF grammar is:

<sort>                  ::= "-|+"? <property> ( "," <property> )*
<property>              ::= <strictString> ( "." <strictString> )*
<strictString>          ::= ( <char> | <digit> | "_" | "-" )+

[313] SHOULD name sort enum values with the ressource properties names (w/ prefix)

Sorting options should be named in compliance with the actual ressource property names the sorting is applied on.

?sort=lastName,firstName
?sort=-age

[320] SHOULD name filtering query parameters in conformity with the relevant property name when applying equality on an existing property

When query parameters are used as a way to filter resources based on the value of one of their properties, then the query parameter SHOULD be named with the same name as the relevant property.

[321] MUST use camelCase for filtering query parameter names

As a result of the previous rule, query parameters MUST be named using the same casing as properties: camelCase.

GET /lucca-api/employees?payrollIdentifier=00123 HTTPS/1.1

[322] SHOULD stick to the JSON object structure (JSON path) when naming query parameters

When these query parameters filter on a nested property (i.e. the property of an object property in the resource representation), then the query parameter name SHOULD stick to the JSON path to said property (i.e. list the properties from the root object, separated with a dot “.” character). Examples:

?department.id=12
?department.head.lastName=Doe

[323] SHOULD avoid default values on filtering query parameters.

Unless it absolutely makes sense, in which case the default value MUST be documented in the OpenAPI specs.

[324] SHOULD support an array of values on equality operator filtering

When applying an equality filter on one property of the resource, then you should support multiple values. In this case, values must be serialized as a comma-separated list:

?status=pending,approved,denied

[325] SHOULD support date-range values when filtering on date or date-time properties through a `{propName}.between` named query parameter

TODO

[326] MUST represent date-range query parameter values in compliance with ISO 8601:

date-fullyear         = 4DIGIT
date-month            = 2DIGIT  ; 01-12
date-mday             = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on month/year
time-hour             = 2DIGIT  ; 00-23
time-minute           = 2DIGIT  ; 00-59
time-second           = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second rules
time-secfrac          = "." 1*DIGIT
time-numoffset        = ("+" / "-") time-hour ":" time-minute
time-offset           = "Z" / time-numoffset

iso-date              = date-fullyear "-" date-month "-" date-mday
iso-date-time         = iso-date "T" time-hour ":" time-minute ":" time-second [time-secfrac]
iso-date-time-offset  = iso-date-time time-offset

date-range                  = (iso-date / "..") "--" (iso-date / "..")
date-time-range             = (iso-date-time / "..") "--" (iso-date-time / "..")
date-time-offset-ranges     = (iso-date-time-offset / "..") "--" (iso-date-time-offset / "..")

The canonical notation with a “/” (forward slash) delimiter between dates SHOULD not be used as it could break URLs when used as query parameter values.

You MAY choose to support date(-time)-ranges defined with a duration component. You SHOULD support open-handed ranges (i.e. with a “..” start or end).

[327] MUST treat date-ranges as closed intervals, and date-time-ranges as open-handed intervals

Why? Because this is the most common human way of apprehending date and date-time ranges.

2024-01-01--2024-01-31 --> Includes Jan. 31st
2024-01-01T00:00:00Z--2024-01-02T00:00:00Z --> Does not include midnight of Jan. 2nd

Giving API clients control over response exansion is a way of making integrations easier. Nonetheless, be aware that such features may prove costly, due to:

potential poor performance on most complex JOIN requests ;
high payload weight ;
cache fragmentation ;
cache invalidation ;
complexity when parsing elastic response.

[341] MUST stick to the embedding convention when implementing embedding

Paging is handled through two query parameters:

Parameter name	Parameter value type	Example	Description
page	`<string \| int<int32>>`	`?page=2`	The identifier of the page to retrieve.
limit	`int<int32>`	`?limit=100`	The page size. Subject to default and max values.

[360] MUST implement paging on all collections whose length is not controlled

Whenever representing a collection of resources whose maximum size is not constant and can prove high, then make sure to implement paging. Paging is the key to ensuring satisfactory performance.

[361] MUST support cursor-based paging

Cursor-based paging offers better performance than index-based paging, but at the cost of one feature: API clients must iterate through each page (they cannot randomly access a given page), as the cursor of a page is obtained through retrieving the previous or next one.

[362] SHOULD support index-based paging

On top of allowing random-access, index-based paging is also more common and more readily comprehensible by humans.

[361] SHOULD have a “low“ default page size (limit)

Having a low default page size:

Ensures satisfactory response times of random requests.
Encourages clients to properly implement paging.

We recommend having a default page size between 10 and 25.

[362] MUST have a “reasonable” max page size (limit)

For the same reasons as above. We recommend not exceeding 100 items per page.

[363] SHOULD strive to a coherent default paging strategy over the whole API

Monotony reduces complexity. As such, make sure your default as well as max page size are the same for all collections.

[364] MUST support paging links (next, prev)

Paging links consists in giving API clients links to the previous and next page when retrieving a page of resources.

This is absolutely mandatory when implementing cursor-based paging.

Embedding

[400] MAY support embedding in order to given clients control over response expansion

Reponse expansion is considered a good practice as it may reduce the number of required HTTP requests and as such make integrations easier.

[401] MUST conform to the convention when representing embedded ressources

The embedded representation of a resource MUST be in the reserved embedded response property (at the root object level). The embedded property MUST be a JSON object whose keys are the name of the resources types, and its values are a JSON object whose keys are the embedded resources ids and values the related representation.

{
    "embedded": {
        "employee": {
            "416": {
                "id": "416",
                "type": "employee",
                "url": "...",
                "givenName": "John",
                "familyName": "Doe"
            }
        }
    }
}

[402] MAY offer partial representations of embedded ressources

Resource representations embedded in the reserved embedded property MAY be partial, i.e. only serialize a subset of the related resource properties. You MUST make sure the authenticated user has access to the resource when embedding it in the response.

[404] SHOULD invalidate HTTP cache when embeddable ressource state changes

When representing an embedded related resource, then any change to this embedded resource also changes the representation of the embedding representation. As a result, the HTTP cache of the embedding resource SHOULD be invalidated whenever one of its embedded resources changes.

This is a SHOULD and not a MUST. Consequently, embedded resources representations MAY be stale from cache.

This is why the embedding is done at root level rather than nested in the embedding resource representation.

[405] SHOULD NOT trigger a (webhoook) event when an embeddable ressource state changes

In order to avoid events propagation, avoid triggering events on the embedding resource whenever one of its embedded resource is changed, except if the embedding resource bears a property that references this embedding resource. In other words: you SHOULD trigger an event whenever an intrinsic attribute of the resource changes ; and embedded representations are not intrinsic attributes.

Headers

[600] MUST use hyphen-separated Pascal-Case and avoid “X-” prefix when naming headers

Custom headers SHOULD NOT be prefixed with “X-” (this practice was deprecated along with RFC-6648). Header MUST be named using hyphen-separated PascalCase.

[601] SHOULD stick to standard HTTP headers

You SHOULD stick to standard HTTP headers whenever possible.

[602] MUST respect the intended semantic for reserved HTTP headers

Some custom headers are reserved for the Lucca API and as such MUST NOT be used in any other way.

Versioning

[700] SHOULD avoid versioning APIs

Versioning an API should be seen as a last resort when implementing APIs, as it breaks integrations.

[701] SHOULD reduce breaking changes through proper change management

Prefer additions to deletions / modifications. Have a rather “lax” definition of breaking changes. For example: clients should consider all ressources extensibles without breaking. Same with enumerations.

[702] MUST version the Lucca API

The major quality expected of the Lucca API is its stability for clients. As we cannot prevent all breaking changes, a versioning must be implemented.

[703] MUST handle API versioning through the `Api-Version` HTTP header (both requests and responses)

GET /lucca-api/employees HTTP/1.2
Host: example.ilucca.net

> Request
Api-Version: 2024-01-22
Accept: application/json

< Response
Api-Version: 2024-01-01
Content-Type: application/json

{ ... }

[704] SHOULD avoid default version

Either make the Api-Version HTTP header required, or make it possible for clients to “lock” a specific version (e.g. API key based).

[705] SHOULD name version with their release date

You may implement version selection through a “as of” behaviour: the server will select the API version that exactly matches the given version or is the closest prior one.

[706] MUST use the `Deprecation` and `Sunset` HTTP headers to convey an API version lifecycle

For the Deprecation HTTP header, refer to the draft-ietf-httpapi-deprecation-header-03. For the Sunset HTTP header, refer to RFC 8594.

GET /lucca-api/employees HTTP/1.2
Host: example.ilucca.net

> Request
Api-Version: 2018-01-01
Accept: application/json

< Response
Api-Version: 2018-01-01
Deprecation: 2020-04-01
Sunset: 2025-01-01

[707] [Lucca API] MUST support deprecated version for at least 6 months

Once an API version has been deprecated, then it must stay available to all clients for at least 6 months. This date is ideally indicated in the Sunset HTTP response header.

[708] [Lucca API] MUST NOT deprecate an API version prior to 6 months after its initial release

Once an API version is released, it may not be deprecated before a 6 months time period has passed.

[709] MUST notify clients whenever an API version is deprecated

The information should be available to all clients, and you should be extra zealous and notify those that actively use it.

[710] MAY break an already released API version in order to fix bugs, unexpected behaviors or security and performance issues.

In other words: if the deployed API version is not compliant with the spec, then you may fix it even though it could lead to breaking changes (as long as the fix makes it compliant with the spec).

Cache

[730] SHOULD implement default HTTP cache behavior

You should always be explicit regarding cacheability. As default, when not implementing cache, servers and clients should always set the Cache-Control header to Cache-Control: no-store (rather than no-cache). As a reminder:

no-cache: responses may be cached but should be validated before use.
no-store: responses may not ever be cached.

[731] SHOULD support HTTP cache on endpoints exposing stable resources

HTTP Caching is the prime means of building scalable APIs.

[732] MUST conform to the standard semantic of HTTP methods when implementing HTTP cache

Please refer to HTTP methods cacheability.

Events

[900] SHOULD implement events for all mutable resources

Events give API clients more optimal ways of integrating to the Lucca API (polling can prove costly and complex).

[901] SHOULD offer “at-least-once” guarantee to receivers

As a reminder:

“at-most-once”: message may be lost, but if not, will only be delivered once.
“at-least-once”: message may never be lost, but may be delivered more than once.
“exactly-once”: message may never be lost and will never be delivered more than once.

“Exactly-once” is the most difficult delivery guarantee to implement. It sure is friendly to API clients, but it has a high cost for the system’s performance and complexity. Therefore, when implementing the “at-least-once” guarantee, make sure events receivers are idempotent and handle message duplication correctly.

[902] SHOULD avoid ad hoc events and stick to CRUD RESTful events

An Event represents a change in an application state that might be of interest to third-party apps. In order to be properly coordinated with the REST API, an Event must always be a change that is in relation to a single resource represented in the API. In other words:

an event MUST be linked to one affected REST resource.
an event MUST be sent whenever a resource’s (that is subject to events) representation in the API changes (outside of embedded and links).

In other words, embrace data-change events (e.g. job-position.created) and stay clear of business-events (e.g. employee.promoted) as well as free-form events (e.g. employee-10-years-anniversay).

[903] MUST conform to the event schema and topic conventions

“Topic” is synonym to “type of event”.

The event schema is imposed and described in the API Reference.

Events are “fat” (rather than “thin”), i.e. contain the representation of the related resource in order to improve the development experience among receivers.

Topics naming MUST conform to the following conventions:

<op>    ::= "created" | "updated" | "deleted"
<topic> ::= <resource.type> '.' <op>

[904] MUST reserve the “event” term to RESTful events

You may add an affix though, for example: calendar-event.

[905] SHOULD support the `updatedAttributes` on `*.updated` topics

Giving receivers the list of updated attributes on *.updated events. When implementing this feature, you SHOULD serialize a JSON object whose keys are the updated attributes and whose values are their previous value.

[906] MUST sign events when sending them to webhooks

Ensure authenticity of the event (a fake event might be injected or the data of a legitimate event might be forged). To make sure an event has not been tampered with, a cryptographic signature must be used, like HMAC (Hash-based Message Authentication Code). The sender MUST sign the event payload with a shared secret and includes the signature in the Lucca-Signature HTTP header. This offers the following guarantees:

authentication: authenticates the sender ;
non-repudiation: makes sure the sender cannot deny having sent the event ;
integrity: makes sure the content of the event was not tampered with in transit.

In order to protect receivers againts replay attacks (an attacker might record traffic and play it back later), make sure the signature depends on a timestamp that matches the moment the event delivery is attempted. Reeivers need to validate the signature and the timestamp contained in the event (a tolerance of +/- 5 minutes should be applied). In other words, any event older than 5 minutes should be automatically rejected by the subscriber.

[907] SHOULD enforce “fast” responce times on receivers through a timeout

Prevent event flooding: a receiver endpoint might get flooded with events. Best practice is for receivers to “acknowledge receipt of events fast, and queue events for asynchronous processing”. A timeout can help enforce satisfactory response times on receivers (e.g.: Slack imposes a very short 3 seconds timeout on receivers). Otherwise, deliveries will be suspended.

[908] MUST NOT deliver events through uncrypted HTTP requests

For obvious security reasons.

[909] MUST version events along the API

When the API is versioned, then make sure your events are as well (given that the representations of resources embedded in events payload are versioned). When multiple API versions are live, then make sure to generate as many events as there are ongoing versions (one for each version).

[920] MAY support the cloudevents format

CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems.

Get Started

Using Lucca API

Webhooks

Resources

​Get Started

​Motivation

​Content

​How to read these guidelines

​Validating your API specs

​Lucca API building principles

​Required Qualities

​Top-Level Principles

​General Rules

​[001] MUST be RESTful

​[002] SHOULD embrace a design first approach

​[003] SHOULD be robust

​[004] SHOULD NOT surprise clients

​[005] SHOULD always be explicit

​[006] SHOULD embrace an collaborative and iterative design process

​[007] SHOULD define useful resources

​[008] MUST secure your API

​[009] MUST be transparent regarding access rights

​Endpoints

​[100] MUST use kebab-case for paths naming

​[101] SHOULD use paths that conform to resources names

​[102] MUST conform to HTTP methods standard semantics

​[103] MUST avoid having verbs in URLs

​[104] SHOULD NOT show structural relationships in URIs

​[105] SHOULD avoid pathing ambiguity

​[106] MUST use official HTTP status codes

​[107] SHOULD only use most common HTTP status codes

​[108] MUST return a Problem for 4xx and 5xx responses

​[109] [LUCCA-API] MUST indicate x-provider in the spec for each path

​[110] [LUCCA-API] MUST use kebab-case for operationId in the OpenAPI spec for each endpoint

​[111] SHOULD avoid custom media types

​[112] MUST be robust against excessive slashes

​[113] SHOULD avoid polymorphic endpoints

​Schemas

​[200] MUST support the (Internet) JSON format

​[201] MUST return JSON objects as top-level data structures

​[202] MUST name resources properties in camelCase

​[203] MUST conform to semantics of reserved property names

​[204] SHOULD conform to type-dependent suffixes or prefixes

​[205] MUST declare enum values as upper-snake case strings

​[206] MUST define a format for number and integer types

​[207] SHOULD define a minimum and maximum value for number and integer types

​[208] MUST use standard formats for date and time properties

​[209] SHOULD use standard formats for time duration and interval properties

​[210] SHOULD enforce strong validation over types Date(Only), DateTime (floating) and DateTimeOffset.

​[211] MUST use standard formats for country, language and currency properties

​[212] SHOULD / MUST type ids as strings

​[213] SHOULD avoid using UUID

​[214] MAY consider giving clients control over ids

​[215] SHOULD avoid nullable array properties

​[216] MUST avoid nullable boolean properties

​[217] MUST consider null and absent properties as the same

​[218] SHOULD / MUST serialize null properties in responses

​[230] MUST use the common Money object

​[231] MUST use the common WorkEventDuration object

​[240] MUST use Problem schema for error responses

​[250] [LUCCA-API] MUST conform to the Event schema for (webhook) events

​[251] [LUCCA-API] MUST follow naming convention for event topics

​Query Parameters

​[301] MUST not deviate from reserved query parameters intended semantic

​[310] MUST define a default sorting strategy for consistency

​[311] MAY give clients control over the ordering of a collection’s items

​[312] MUST conform to the standard when giving clients control over sorting

​[313] SHOULD name sort enum values with the ressource properties names (w/ prefix)

​[320] SHOULD name filtering query parameters in conformity with the relevant property name when applying equality on an existing property

​[321] MUST use camelCase for filtering query parameter names

​[322] SHOULD stick to the JSON object structure (JSON path) when naming query parameters

​[323] SHOULD avoid default values on filtering query parameters.

​[324] SHOULD support an array of values on equality operator filtering

​[325] SHOULD support date-range values when filtering on date or date-time properties through a {propName}.between named query parameter

​[326] MUST represent date-range query parameter values in compliance with ISO 8601:

​[327] MUST treat date-ranges as closed intervals, and date-time-ranges as open-handed intervals

​[340] MAY support embedding controls in order to give clients the ability to expand responses and include related ressources and/or optional complementary properties

​[341] MUST stick to the embedding convention when implementing embedding

​[360] MUST implement paging on all collections whose length is not controlled

​[361] MUST support cursor-based paging

Get Started

Motivation

Content

How to read these guidelines

Validating your API specs

Lucca API building principles

Required Qualities

Top-Level Principles

General Rules

[001] MUST be RESTful

[002] SHOULD embrace a design first approach

[003] SHOULD be robust

[004] SHOULD NOT surprise clients

[005] SHOULD always be explicit

[006] SHOULD embrace an collaborative and iterative design process

[007] SHOULD define useful resources

[008] MUST secure your API

[009] MUST be transparent regarding access rights

Endpoints

[100] MUST use kebab-case for paths naming

[101] SHOULD use paths that conform to resources names

[102] MUST conform to HTTP methods standard semantics

[103] MUST avoid having verbs in URLs

[104] SHOULD NOT show structural relationships in URIs

[105] SHOULD avoid pathing ambiguity

[106] MUST use official HTTP status codes

[107] SHOULD only use most common HTTP status codes

[108] MUST return a Problem for 4xx and 5xx responses

[109] [LUCCA-API] MUST indicate x-provider in the spec for each path

[110] [LUCCA-API] MUST use kebab-case for operationId in the OpenAPI spec for each endpoint

[111] SHOULD avoid custom media types

[112] MUST be robust against excessive slashes

[113] SHOULD avoid polymorphic endpoints

Schemas

[200] MUST support the (Internet) JSON format

[201] MUST return JSON objects as top-level data structures

[202] MUST name resources properties in camelCase

[203] MUST conform to semantics of reserved property names

[204] SHOULD conform to type-dependent suffixes or prefixes

[205] MUST declare enum values as upper-snake case strings

[206] MUST define a format for number and integer types

[207] SHOULD define a minimum and maximum value for number and integer types

[208] MUST use standard formats for date and time properties

[209] SHOULD use standard formats for time duration and interval properties

[210] SHOULD enforce strong validation over types Date(Only), DateTime (floating) and DateTimeOffset.

[211] MUST use standard formats for country, language and currency properties

[212] SHOULD / MUST type ids as strings

[213] SHOULD avoid using UUID

[214] MAY consider giving clients control over ids

[215] SHOULD avoid nullable array properties

[216] MUST avoid nullable boolean properties

[217] MUST consider null and absent properties as the same

[218] SHOULD / MUST serialize null properties in responses

[230] MUST use the common Money object

[231] MUST use the common WorkEventDuration object

[240] MUST use Problem schema for error responses

[250] [LUCCA-API] MUST conform to the Event schema for (webhook) events

[251] [LUCCA-API] MUST follow naming convention for event topics

Query Parameters

[301] MUST not deviate from reserved query parameters intended semantic

[310] MUST define a default sorting strategy for consistency

[311] MAY give clients control over the ordering of a collection’s items

[312] MUST conform to the standard when giving clients control over sorting

[313] SHOULD name sort enum values with the ressource properties names (w/ prefix)

[320] SHOULD name filtering query parameters in conformity with the relevant property name when applying equality on an existing property

[321] MUST use camelCase for filtering query parameter names

[322] SHOULD stick to the JSON object structure (JSON path) when naming query parameters

[323] SHOULD avoid default values on filtering query parameters.

[324] SHOULD support an array of values on equality operator filtering

[325] SHOULD support date-range values when filtering on date or date-time properties through a `{propName}.between` named query parameter

[326] MUST represent date-range query parameter values in compliance with ISO 8601:

[327] MUST treat date-ranges as closed intervals, and date-time-ranges as open-handed intervals

[340] MAY support embedding controls in order to give clients the ability to expand responses and include related ressources and/or optional complementary properties

[341] MUST stick to the embedding convention when implementing embedding

[360] MUST implement paging on all collections whose length is not controlled

[361] MUST support cursor-based paging

[362] SHOULD support index-based paging

[361] SHOULD have a “low“ default page size (limit)

[362] MUST have a “reasonable” max page size (limit)

[363] SHOULD strive to a coherent default paging strategy over the whole API