// ----------------------------------------------------------------------------- // Enum Typedefs // ----------------------------------------------------------------------------- /** * @typedef {"name" | "created_at" | "updated_at" | "visibility"} AppSortBy */ /** * @typedef {"api_json" | "avro_idl" | "service_json" | "swagger"} OriginalType */ /** * A publication represents something that a user can subscribe to. An example would be subscribing to an email alert whenever a new version of an application is created. * @typedef {"membership_requests.create" | "memberships.create" | "applications.create" | "versions.create" | "versions.material_change"} Publication */ /** * @typedef {"asc" | "desc"} SortOrder */ /** * Controls who is able to view this version * @typedef {"user" | "organization" | "public"} Visibility */ // ----------------------------------------------------------------------------- // Model Typedefs // ----------------------------------------------------------------------------- /** * An application has a name and multiple versions of its API. * @typedef {Object} Application * @property {string} guid Internal unique identifier for this application. * @property {Reference} organization * @property {string} name The unique name for this application. * @property {string} key Used as a unique key in the URL path. Key is automatically derived from the application name. * @property {Visibility} visibility Controls who is able to view this application * @property {string} [description] * @property {string} last_updated_at The updated_at of this application or created_at of it's latest version * @property {Audit} audit */ /** * @typedef {Object} ApplicationForm * @property {string} name * @property {string} [key] Defaults to a key generated from the application name * @property {string} [description] * @property {Visibility} visibility */ /** * @typedef {Object} ApplicationMetadata * @property {string} guid Internal unique identifier for this application. * @property {string} key Used as a unique key in the URL path. Key is automatically derived from the application name. */ /** * Describes the versions associated with a given application * @typedef {Object} ApplicationMetadataVersion * @property {string} version */ /** * Summary of an application sufficient for display and links * @typedef {Object} ApplicationSummary * @property {string} guid * @property {Reference} organization * @property {string} key */ /** * Attributes are globally unique key which allow users to specify additional content to pass in to the code generators. * @typedef {Object} Attribute * @property {string} guid Internal unique identifier for this attribute. * @property {string} name The name of the attribute. Globally unique and an 'identifier' (lower case, url safe, etc.) * @property {string} [description] Optional description - a good description here will indicate which code generators it applies to and what effect it will have on those code generators. * @property {Audit} audit */ /** * @typedef {Object} AttributeForm * @property {string} name * @property {string} [description] */ /** * @typedef {Object} AttributeSummary * @property {string} guid Internal unique identifier for this attribute. * @property {string} name The name of the attribute. Globally unique and an 'identifier' (lower case, url safe, etc.) */ /** * Attribute values can be set at different levels. Initially we support setting organization wide attributes, but in the future plan to support setting attribute values with each version of the application. * @typedef {Object} AttributeValue * @property {string} guid Internal unique identifier for this attribute value. * @property {AttributeSummary} attribute * @property {string} value * @property {Audit} audit */ /** * @typedef {Object} AttributeValueForm * @property {string} value */ /** * Represents the result of a successful authorization * @typedef {Object} Authentication * @property {User} user * @property {Session} session */ /** * @typedef {Object} BatchDownloadApplicationForm * @property {string} application_key * @property {string} version */ /** * @typedef {Object} BatchDownloadApplications * @property {Version[]} applications */ /** * @typedef {Object} BatchDownloadApplicationsForm * @property {BatchDownloadApplicationForm[]} applications */ /** * Represents a single change from one version of a service to another * @typedef {Object} Change * @property {string} guid * @property {Reference} organization * @property {Reference} application * @property {ChangeVersion} from_version * @property {ChangeVersion} to_version * @property {Diff} diff * @property {string} changed_at Records the timestamp of when the actual change occurred (vs. when we created the changed record) * @property {UserSummary} changed_by Records who made the actual change * @property {Audit} audit */ /** * Represents a simpler model of a version specifically for the use case of displaying changes * @typedef {Object} ChangeVersion * @property {string} guid * @property {string} version */ /** * Separate resource used only for the few actions that require the full token. * @typedef {Object} CleartextToken * @property {string} token The actual token. Guaranteed to be globally unique. */ /** * Generated source code. * @typedef {Object} Code * @property {GeneratorWithService} generator * @property {string} source The actual source code. * @property {File[]} files A collection of source files */ /** * @typedef {Object} CodeForm * @property {Attribute[]} attributes */ /** * Represents a single breaking diff of an application version. A breaking diff indicates that it is possible for an existing client to now experience an error or invalid data due to the diff. * @typedef {Object} DiffBreaking * @property {string} description * @property {boolean} is_material */ /** * Represents a single NON breaking diff of an application version. * @typedef {Object} DiffNonBreaking * @property {string} description * @property {boolean} is_material */ /** * Represents a single domain name (e.g. www.apibuilder.io). When a new user registers and confirms their email, we automatically associate that user with a member of the organization associated with their domain. For example, if you confirm your account with an email address of example@somedomain.com, we will automatically create a membership request on your behalf to join the organization with domain somedomain.com. * @typedef {Object} Domain * @property {string} name The domain name */ /** * Data used to confirm an email address. The token is an internal unique identifier used to lookup the specific email address and user account for which we sent an email verification email. * @typedef {Object} EmailVerificationConfirmationForm * @property {string} token */ /** * @typedef {Object} Error * @property {string} code Machine readable code for this specific error message * @property {string} message Description of the error */ /** * @typedef {Object} GeneratorForm * @property {string} service_guid * @property {Generator} generator */ /** * Defines a service that provides one or more code generators * @typedef {Object} GeneratorService * @property {string} guid * @property {string} uri * @property {Audit} audit */ /** * @typedef {Object} GeneratorServiceForm * @property {string} uri */ /** * Wraps a service and a generator providing easier access for applications. * @typedef {Object} GeneratorWithService * @property {GeneratorService} service * @property {Generator} generator */ /** * When searching for content, the results of the search will be a list of items. Each item will have enough information to render for the user, including a type and item_guid to enable creating the appropriate link. * @typedef {Object} Item * @property {string} guid Unique identifer for this item. By using a UUID, you can combine with the type to figure out the URI for the resource * @property {ItemDetail} detail * @property {string} label * @property {string} [description] */ /** * A membership represents a user in a specific role to an organization. Memberships cannot be created directly. Instead you first create a membership request, then that request is either accepted or declined. * @typedef {Object} Membership * @property {string} guid Internal unique identifier for this membership. * @property {User} user * @property {Organization} organization * @property {MembershipRole} role The role this user plays for this organization. Typically member or admin. * @property {Audit} audit */ /** * A membership request represents a user requesting to join an organization with a specific role (e.g. as a member or an admin). Membership requests can be reviewed by any current admin of the organization who can either accept or decline the request. * @typedef {Object} MembershipRequest * @property {string} guid Internal unique identifier for this membership request. * @property {User} user * @property {Organization} organization * @property {MembershipRole} role The requested role for membership to this organization. Typically member or admin. * @property {Audit} audit */ /** * @typedef {Object} MoveForm * @property {string} org_key The key of the organization to which we are moving this item */ /** * An organization is used to group a set of applications together. * @typedef {Object} Organization * @property {string} guid Internal unique identifier for this organization. * @property {string} key Used as a unique key in the URL path. Key is automatically derived from the organization name. * @property {string} name The name of this organization. * @property {string} namespace Global namespace for this organization. * @property {Visibility} visibility * @property {Domain[]} domains * @property {Audit} audit */ /** * @typedef {Object} OrganizationForm * @property {string} name * @property {string} [key] Defaults to a url friendy version of the name * @property {string} namespace Global namespace for this organization. * @property {Visibility} visibility Public organizations will be listed in apibuilder directory. Organizations with visibility organization will only be visible to members of that org. * @property {string[]} [domains] */ /** * Represents the original input used to create an application version * @typedef {Object} Original * @property {OriginalType} type * @property {string} data */ /** * @typedef {Object} OriginalForm * @property {OriginalType} [type] If not specified, we set the type by inspecting the data * @property {string} data */ /** * Allows a user to change their password with authentication from a token. * @typedef {Object} PasswordReset * @property {string} token Unique one time use token to change a password * @property {string} password */ /** * Create a password reset request - e.g. an email containing a one time URL to change a password * @typedef {Object} PasswordResetRequest * @property {string} email The email address for which we generate the password reset. */ /** * Represents a user sessions (e.g. user logged into site) * @typedef {Object} Session * @property {string} id Cryptographically secure session id * @property {string} expires_at */ /** * Represents a user that is currently subscribed to a publication * @typedef {Object} Subscription * @property {string} guid Internal unique identifier for this subscription record * @property {Organization} organization * @property {User} user * @property {Publication} publication * @property {Audit} audit */ /** * @typedef {Object} SubscriptionForm * @property {string} organization_key * @property {string} user_guid * @property {Publication} publication */ /** * A token gives a user access to the API. * @typedef {Object} Token * @property {string} guid Internal unique identifier for this token. * @property {User} user The user to which this token belongs. * @property {string} masked_token The masked from of the token. * @property {string} [description] optional description to help the user manage the token. * @property {Audit} audit */ /** * @typedef {Object} TokenForm * @property {string} user_guid The user for which we are creating the token. * @property {string} [description] */ /** * A user is a top level person interacting with the api doc server. * @typedef {Object} User * @property {string} guid Internal unique identifier for this user. * @property {string} email * @property {string} nickname Public unique identifier for this user. * @property {string} [name] * @property {Audit} audit */ /** * @typedef {Object} UserForm * @property {string} email * @property {string} password * @property {string} [nickname] Defaults to a unique identifier based on email address * @property {string} [name] */ /** * Summary of a user sufficient for display * @typedef {Object} UserSummary * @property {string} guid * @property {string} nickname */ /** * @typedef {Object} UserUpdateForm * @property {string} email * @property {string} nickname * @property {string} [name] */ /** * Used only to validate json files - used as a resource where http status code defines success * @typedef {Object} Validation * @property {boolean} valid If true, the json schema is valid. If false, there is at least one validation error. * @property {string[]} errors Contains any validation errors that result from parsing the json document. If empty, the document is valid. */ /** * Represents a unique version of the application. * @typedef {Object} Version * @property {string} guid Internal unique identifier for this version. * @property {Reference} organization * @property {Reference} application * @property {string} version The tag for this version. Can be anything, but if semver style version number is used, we automatically correctly sort by version number to find latest. Otherwise latest version is considered to be the most recently created. * @property {Original} [original] The original uploaded file describing this version, if available * @property {Service} service spec/spec.json description of this API * @property {Audit} audit */ /** * @typedef {Object} VersionForm * @property {OriginalForm} original_form * @property {Visibility} [visibility] If provided, updates the visibility for all versions of this application */ /** * Users can watch individual applications which enables features like receiving an email notification when there is a new version of an application. * @typedef {Object} Watch * @property {string} guid Internal unique identifier for this watch * @property {User} user * @property {Organization} organization * @property {Application} application * @property {Audit} audit */ /** * @typedef {Object} WatchForm * @property {string} user_guid * @property {string} organization_key * @property {string} application_key */ // ----------------------------------------------------------------------------- // Union Typedefs // ----------------------------------------------------------------------------- /** * Represents a single diff in an application * @typedef {(DiffBreaking & { type: "diff_breaking" } | DiffNonBreaking & { type: "diff_non_breaking" })} Diff */ /** * Identifies the specific type of item that was indexed by search * @typedef {(ApplicationSummary & { type: "application_summary" })} ItemDetail */