liveBookmanning.com

What you will learn in API Design Patterns

by John J. (JJ) Geewax

Read it on liveBook Get the book at manning.com

Chapter by chapter

Concepts explained in this book

• filteringFiltering is the selection of items that satisfy specified conditions before results are returned or processed.
• unique identifierAn identifier is a value that uniquely distinguishes an entity or resource within a relevant system or scope.
• referenceA reference is a pointer stored in a resource that identifies official data held elsewhere.
• HTTP methodAn HTTP method is a standardized request action indicating how an HTTP client intends to interact with a resource.
• backward compatibilityBackward compatibility is the property of a changed software interface remaining usable by previously written clients or consumers.
• export methodAn export operation retrieves data from a system and sends it to an external storage destination.
• resource revisionResource revisioning is the practice of retaining distinct historical states of an API resource as it is modified over time.
• field maskA field mask is an API specification that identifies which fields of a resource or response should be selected or modified.
• consistencyData consistency is the property that related views or copies of data agree with one another and reflect an appropriate current state.
• long-running taskA long-running operation is an API operation whose completion may be delayed and whose eventual result is obtained asynchronously.
• contractAn application programming interface is a defined interface through which software programs interact with a system's functionality or data.
• revision identifierA revision identifier is a value that distinguishes one revision of an API resource from other revisions of that resource.
• soft deletionSoft deletion is a deletion technique that marks a resource as deleted while retaining it until later physical removal or completion of a deletion process.
• backward compatibility policyA compatibility policy is a set of rules defining which changes an API permits while preserving compatibility for its users.
• list methodA list method is a standard API operation that returns the resources belonging to a specified collection.
• association resourceAn association resource is an API resource that represents a relationship between specific resources and whose associated endpoints are fixed for the resource's lifetime.
• semantic changeA semantic change modifies the meaning, behavior, or interpretation associated with an API resource, field, or operation.
• retryA retry is a subsequent attempt to perform an operation after an earlier attempt fails.
• custom filter functionA custom filter function is a predefined callable extension of filter syntax that performs a narrowly controlled operation.
• polymorphic resourceA polymorphic resource is an API resource whose generic interface can represent multiple specific resource implementations with implementation-dependent behavior.
• missing valueA missing value is a value that is absent because its field is omitted rather than explicitly assigned.
• move methodResource moving is the relocation of an API resource so that it belongs to a different parent or location.
• atomicityAtomicity is the property of treating a multi-step operation as an indivisible unit whose effects are either all applied or all undone.
• response dedupingRequest deduplication is the technique of recognizing repeated requests for the same operation and preventing their effects from being applied more than once.
• side effectA side effect is an observable state change or additional operation caused by an action beyond its primary specified result.
• expiration dateAn expiration time is the point in time after which a resource is intended to be deleted or otherwise no longer retained.
• parent-child relationshipA hierarchical relationship is a parent-child relationship in which resources occupy different levels of an ordered structure.
• digital signatureA digital signature is a cryptographic value generated with a private key and verifiable with the corresponding public key to authenticate the signer and detect changes to signed data.
• deletionA delete method is an API operation that removes an existing resource.
• predictabilityPredictability is the property of a system or naming scheme whose meanings and behavior can be reliably inferred from established patterns.
• design patternA design pattern is a reusable, established solution structure for recurring software design problems.
• resourceAn API resource is a named conceptual entity that the API stores, exposes, or allows clients to manipulate.
• exponential backoffExponential backoff is a retry strategy that increases the delay between successive attempts, typically by a multiplicative factor.
• default valueA default value is a value automatically selected when an API request or data field does not specify an explicit value.
• idempotencyAn idempotent method is an API operation whose repeated execution has the same effect as executing it once.
• request idA request identifier is a value associated with an API request so that the request can be distinguished, tracked, and recognized across repeated attempts.
• singleton sub-resourceA singleton sub-resource is an API sub-resource representing one distinct related entity rather than a collection of entities.
• atomic typeA data type is a classification that specifies the kind of value a field can contain and how that value is represented.
• page tokenA next page token is an opaque identifier returned by an API to indicate how a client can request the next page of results.
• MapA map is a collection of key-value pairs in which keys identify associated values and may be dynamically defined.
• resource layoutA resource hierarchy is the organization of API resources into nested parent-child paths and collections.
• GetOperation methodThe GetOperation method is an API method that retrieves an operation resource and reports errors encountered while retrieving that resource separately from errors produced by the operation.
• serializationA serialization protocol is a defined mechanism for converting structured data into a transferable representation and reconstructing it later.
• deprecation policyA deprecation policy is a set of rules specifying how long deprecated API versions remain available and when they are expected to stop working.
• authorizationAuthorization is the determination of whether an authenticated user is permitted to perform a requested operation.
• paginationPagination is the division of a collection of results into separately retrievable pages.
• backup and restoreA backup is a preserved copy of data intended to support recovery or restoration of the original data.
• tradeoffA trade-off is a balance in which gaining one benefit or property requires accepting a corresponding disadvantage or cost.
• undeleteAn undelete method is an API operation that restores a resource marked as deleted without requiring the resource to be recreated.
• validation requestA validation request is an API request that evaluates which resources satisfy criteria without applying the corresponding destructive operation.
• referential integrityReferential integrity is the property that references remain valid and continue to identify the intended existing resources or data.
• snapshotA snapshot is a point-in-time view of stored data that preserves the data state as of a particular instant.
• promiseA promise is an object or abstraction representing the eventual completion or failure of an asynchronous computation.
• request fingerprintA request fingerprint is a derived value representing the contents or relevant properties of an API request for comparison with other requests.
• checksumA checksum value is derived data appended to an identifier to help verify that the identifier was received or entered correctly.
• dynamic data structureA dynamic data structure permits fields or keys to be present or absent rather than requiring a fixed structure for every value.
• HTTP GETA GET method is a standard API method that retrieves the data stored for one identified resource without altering it.
• public keyA public key is the openly distributable component of an asymmetric cryptographic key pair used to verify signatures or perform other public-key operations.
• state fieldA state field is a resource field whose value represents the resource's current state.
• self-reference relationshipA self-reference relationship is a relationship in which entities of one resource type reference other entities of the same type.
• cursorA cursor is a position marker that identifies the point from which the next portion of paged data should be retrieved.
• metadataOperation metadata is auxiliary information describing the progress or other properties of an executing or completed operation.
• InputConfigInputConfig is a configuration object that specifies how externally supplied bytes are decoded and prepared for import.
• OutputConfigOutputConfig is a configuration interface specifying how an export operation transforms and transports outgoing data.
• cachingA cache is a stored copy of data retained for faster or more convenient access than retrieving the original data again.
• pollingA polling loop is a repeated sequence of requests that checks an asynchronous operation until a completion condition is reached.
• write methodA write method is an API operation that adds entries to a collection or submits data for streaming processing without creating a resource representation.
• major versionA major version is the first component of a semantic version that indicates a backward-incompatible change.
• resource orientationA resource-oriented API organizes an interface around named resources and a limited standardized set of operations that apply to those resources.
• full replacementFull replacement is replacing an entire existing resource representation rather than changing only selected parts.
• listA list is an ordered collection of values that can be addressed by position and may contain nested lists or other data types.
• booleanA boolean is a primitive data type whose value is one of two logical states, typically true or false.
• authenticationAuthentication is the process of verifying a claimed identity using evidence such as a credential or cryptographic proof.
• database transactionTransactional semantics are execution rules in which multiple data changes are committed together or rolled back together as one unit.
• Digest headerA digest header is an HTTP header containing a digest that represents the content of a request body.
• polymorphismPolymorphism is an object-oriented programming technique that allows common interfaces to be used across different concrete types while hiding type-specific implementation details.
• data formatA serialization format is a defined representation for converting structured data into a transmissible or storable form and reconstructing it later.
• bytesByte data is binary content represented as a sequence of bytes.
• ciphertextAn encrypted value is data transformed by encryption so that its original content cannot be read without the required key or decryption process.
• partial retrievalPartial retrieval is obtaining only selected portions of a resource or collection rather than its complete representation.
• collection nameA collection name is the identifier for a URL or API element representing multiple instances of a resource.
• purge methodA purge method is a book-specific API method that identifies resources by criteria and deletes the matching resources when deletion is explicitly forced.
• deprecationDeprecated is the API version lifecycle state in which a former current version remains available under current-version change restrictions but is scheduled for removal.
• export failureAn export failure is an unsuccessful attempt to read API resources or transport and write their data to external storage.
• import failureAn import failure is an unsuccessful attempt to read externally supplied data or create its resources in an API.
• import request identifierAn import request identifier is a globally unique value assigned to an imported record so repeated attempts can be recognized as the same record.
• content fieldA content field is a resource field whose meaning and value structure represent the content associated with a resource subtype.
• superset arrangementA superset arrangement represents a polymorphic resource with fields covering the information required by all of its individual subtypes.
• type fieldA type field is a resource field that identifies which subtype or representation applies to a polymorphic resource instance.
• lifecycleA version lifecycle is the ordered progression of an API version through preview, current, deprecated, and deleted states.
• zero valueA zero value is the empty or numerically zero representation that a data format or type uses when no distinct null representation is available.
• validate-only fieldValidation-only mode checks whether a request is valid without applying the requested operation.
• stability guaranteeStability is the property of an API remaining unchanged over time, including in ways affected by its underlying software and infrastructure.
• upper boundAn upper bound is a maximum permitted size or value that a quantity cannot exceed.
• one-to-many relationshipA one-to-many relationship is an association in which one entity may be related to multiple entities while each related entity has at most one corresponding entity on the other side.
• nonrepudiationNonrepudiation is assurance that an actor cannot credibly deny having originated a request or message after its origin has been established.
• semantic versioningA semantic version string is a dotted three-number representation whose major, minor, and patch components communicate the nature of software changes.
• imperative moodThe imperative mood expresses a command or instruction directed at an actor.
• indicative moodThe indicative mood expresses a statement or question about a state or condition rather than a command.
• pluralizationPluralization is the grammatical process of forming a word that denotes more than one instance of a noun.
• prepositionA preposition is a grammatical word that expresses a relationship between a noun phrase and other elements of a phrase or sentence.
• simplicitySimplicity is the API design quality of exposing desired functionality straightforwardly without unnecessary user-facing complexity.
• wildcardA wildcard is a symbol or placeholder that stands for an unspecified value or set of values in a pattern or identifier.
• related resourceA related resource is an API resource connected to a target resource through a reference without necessarily being nested beneath it.
• fulfilled stateResolution is the successful completion of an asynchronous computation with its final value available.
• wait methodA wait method is a custom API method that holds a request until an operation is resolved or rejected.
• waitWaiting is an asynchronous-operation retrieval strategy that keeps a request open until the operation reaches a terminal state.
• polymorphic methodA polymorphic method is an API method whose meaning or behavior varies according to the concrete resource type on which it operates.
• data integrityIntegrity is the property that received data exactly matches the data that was sent and has not been altered in transit.
• string filter representationA string filter representation expresses filtering criteria as a text value interpreted according to a filter syntax.
• parsingParsing is the process of analyzing a serialized or textual representation according to syntax rules to produce a structured or executable form.
• structured filter representationA structured filter representation encodes filtering criteria as structured data conforming to a defined schema.
• unstructured filter representationAn unstructured filter representation encodes filtering criteria as text that conforms to a syntax interpreted by the API server.
• state transitionA state transition is a change of a resource from one status or condition to another.
• api patternAn API design pattern is a reusable solution structure for designing and structuring an API's interface and, sometimes, its externally observable behavior.
• strong consistencyStrong consistency is a consistency guarantee under which reads reflect the relevant latest committed state and do not proceed across conflicting modifications.
• couplingLoose coupling is a design property in which components depend on one another through limited, stable contracts and can change independently.
• data inliningData inlining is storing related information directly within a resource instead of representing it as a separate resource.
• canonical formA canonical form is the single standardized representation selected as the definitive form of equivalent values or inputs.
• create methodA create method is an API operation that creates a new resource from client-provided information and returns the created resource.
• flexibilityFlexibility is the property of an interface that allows users or client code to accommodate changes without losing functionality.
• private keyA private key is the confidential component of an asymmetric cryptographic key pair used to generate digital signatures or perform other private-key operations.
• rigidityRigidity is the property of an interface in which small changes can cause client failures or require substantial adaptation.
• agile instabilityAgile instability is an API versioning strategy that maintains a small sliding window of versions and frequently deprecates older versions to deliver new functionality quickly.
• current stateCurrent is the API version lifecycle state for the primary version offered to users with changes restricted to mandatory requirements and critical fixes.
• deleted stateDeleted is the API version lifecycle state in which a version has been removed and is no longer accessible.
• preview statePreview is an API version lifecycle state in which functionality may change freely and stability is not guaranteed.
• sliding windowA sliding window is a bounded set of currently active versions that advances as newer versions replace older ones.
• remote procedure callA remote procedure call is a mechanism for invoking a procedure or method whose execution occurs on another computer or process.
• rpc-oriented apiAn RPC-oriented API organizes its interface primarily around named operations that perform actions, typically by invoking remote procedures.
• import/export patternThe import/export pattern is a reusable API structure for transferring substantial amounts of data into or out of a service while accommodating destinations, transformations, and asynchronous processing.
• long-running operations patternThe long-running operations pattern is an API structure for representing work that continues after the initial request and exposing its status or result asynchronously.
• output configuration interfaceAn output configuration interface is an API interface that specifies the destination and processing options for exported data.
• api namingAn API name is a user-visible identifier assigned to an API element such as a function, method, resource, or field.
• securitySecurity is the protection of systems and resources against unauthorized access, misuse, or exploitation.
• lower boundA lower bound is the smallest permitted value of a numeric quantity.
• entryAn entry is an anonymous data point submitted to an API through a write method and not individually addressable afterward.
• common caseThe common case is the frequent, typical usage scenario that an API should make especially easy to perform.
• batch get methodA batch get method is an API operation that retrieves multiple specified resources by accepting a group of resource identifiers.
• explicit revisionAn explicit revision is a resource revision created only when a user specifically requests its creation.
• implicit revisionAn implicit revision is a resource revision that an API creates automatically according to changes, schedules, or other system-defined conditions.
• copy or move operationA copy or move operation duplicates or relocates an API resource while applying the destination resource's constraints.
• custom data typeA custom data type is a structured type with a predefined set of keys and specified types for their corresponding values.
• custom expunge methodAn expunge method is an API operation that permanently removes a resource and its data, regardless of whether the resource was previously soft-deleted.
• custom create revision methodA custom create revision method is an API operation that captures the current state of a resource as a new revision.
• metadata interfaceA metadata type is the structured type of auxiliary information associated with an API operation.
• user-chosen identifierA user-chosen identifier is a resource identifier selected by the API consumer rather than generated by the service.
• code pointA Unicode code point is a numeric value assigned by Unicode to identify a character or other encoded abstract element.
• Retry-After indicatorThe Retry-After header is an HTTP response header that indicates how long a client should wait before making a subsequent request or the time at which it may retry.
• request targetA request target is the canonicalized request-line component that identifies an HTTP action and its target path.
• managing resourceA managing resource is the resource that controls which subordinate resources are added or removed in a directed relationship.
• repeated fieldA repeated field is an API or message field that can contain multiple values or items of the same conceptual field.
• stable identityA stable identifier is an identifier whose association with an entity remains unchanged over the entity's relevant lifetime.
• data lossData loss is the unintended removal or destruction of information that should have been retained.
• dynamic key-value mapA dynamic key-value map is a map whose keys are arbitrary and not known when an API schema is defined.
• schemaA schema is a formal specification of the structure, allowed contents, and constraints of data.
• jobA job is an API resource that stores configuration for work and exposes a separate operation for executing that work.
• dangling pointerA dangling pointer is a pointer that refers to a data object or resource that no longer exists.

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.