@@ 4,7 4,7 @@ scalar Cursor
scalar Time
scalar Upload
-# Used to provide a human-friendly description of an access scope
+"Used to provide a human-friendly description of an access scope"
directive @scopehelp(details: String!) on ENUM_VALUE
enum AccessScope {
@@ 19,8 19,10 @@ enum AccessKind {
RW @scopehelp(details: "read and write")
}
-# Decorates fields for which access requires a particular OAuth 2.0 scope with
-# read or write access.
+"""
+Decorates fields for which access requires a particular OAuth 2.0 scope with
+read or write access.
+"""
directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION
# https://semver.org
@@ 29,41 31,43 @@ type Version {
minor: Int!
patch: Int!
- # If this API version is scheduled for deprecation, this is the date on which
- # it will stop working; or null if this API version is not scheduled for
- # deprecation.
+ """
+ If this API version is scheduled for deprecation, this is the date on which
+ it will stop working; or null if this API version is not scheduled for
+ deprecation.
+ """
deprecationDate: Time
- # Optional features
+ "Optional features"
features: Features!
- # Config settings
+ "Config settings"
settings: Settings!
}
-# Describes the status of optional features
+"Describes the status of optional features"
type Features {
artifacts: Boolean!
}
-# Instance specific settings
+"Instance specific settings"
type Settings {
sshUser: String!
}
enum AccessMode {
- # Read-only
+ "Read-only"
RO
- # Read/write
+ "Read/write"
RW
}
enum Visibility {
- # Visible to everyone, listed on your profile
+ "Visible to everyone, listed on your profile"
PUBLIC
- # Visible to everyone (if they know the URL), not listed on your profile
+ "Visible to everyone (if they know the URL), not listed on your profile"
UNLISTED
- # Not visible to anyone except those explicitly added to the access list
+ "Not visible to anyone except those explicitly added to the access list"
PRIVATE
}
@@ 71,8 75,10 @@ interface Entity {
id: Int!
created: Time!
updated: Time!
- # The canonical name of this entity. For users, this is their username
- # prefixed with '~'. Additional entity types will be supported in the future.
+ """
+ The canonical name of this entity. For users, this is their username
+ prefixed with '~'. Additional entity types will be supported in the future.
+ """
canonicalName: String!
repositories(cursor: Cursor, filter: Filter): RepositoryCursor! @access(scope: REPOSITORIES, kind: RO)
@@ 101,14 107,18 @@ type Repository {
description: String
visibility: Visibility!
- # The repository's custom README, if set.
- #
- # NOTICE: This returns unsanitized HTML. It is the client's responsibility to
- # sanitize this for display on the web, if so desired.
+ """
+ The repository's custom README, if set.
+
+ NOTICE: This returns unsanitized HTML. It is the client's responsibility to
+ sanitize this for display on the web, if so desired.
+ """
readme: String
- # If this repository was cloned from another, this is set to the original
- # clone URL.
+ """
+ If this repository was cloned from another, this is set to the original
+ clone URL.
+ """
upstreamUrl: String
accessControlList(cursor: Cursor): ACLCursor! @access(scope: ACLS, kind: RO)
@@ 121,80 131,94 @@ type Repository {
## Porcelain API:
# NOTE: revspecs are git-compatible, e.g. "HEAD~4", "master", "9790b10")
-
- # The HEAD reference for this repository (equivalent to the default branch)
+
+ "The HEAD reference for this repository (equivalent to the default branch)"
HEAD: Reference @access(scope: OBJECTS, kind: RO)
- # Returns a list of comments sorted by committer time (similar to `git log`'s
- # default ordering).
- #
- # If `from` is specified, it is interpreted as a revspec to start logging
- # from. A clever reader may notice that using commits[-1].from + "^" as the
- # from parameter is equivalent to passing the cursor to the next call.
+ """
+ Returns a list of comments sorted by committer time (similar to `git log`'s
+ default ordering).
+
+ If `from` is specified, it is interpreted as a revspec to start logging
+ from. A clever reader may notice that using commits[-1].from + "^" as the
+ from parameter is equivalent to passing the cursor to the next call.
+ """
log(cursor: Cursor, from: String): CommitCursor! @access(scope: OBJECTS, kind: RO)
- # Returns a tree entry for a given path, at the given revspec.
+ "Returns a tree entry for a given path, at the given revspec."
path(revspec: String = "HEAD", path: String!): TreeEntry @access(scope: OBJECTS, kind: RO)
- # Returns the commit for a given revspec.
+ "Returns the commit for a given revspec."
revparse_single(revspec: String!): Commit @access(scope: OBJECTS, kind: RO)
}
-# A cursor for enumerating a list of repositories
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating a list of repositories
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
type RepositoryCursor {
results: [Repository!]!
cursor: Cursor
}
-# A cursor for enumerating access control list entries
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating access control list entries
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
type ACLCursor {
results: [ACL!]!
cursor: Cursor
}
-# A cursor for enumerating a list of references
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating a list of references
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
type ReferenceCursor {
results: [Reference!]!
cursor: Cursor
}
-# A cursor for enumerating commits
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating commits
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
type CommitCursor {
results: [Commit!]!
cursor: Cursor
}
-# A cursor for enumerating tree entries
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating tree entries
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
type TreeEntryCursor {
results: [TreeEntry!]!
cursor: Cursor
}
-# A cursor for enumerating artifacts
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating artifacts
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
type ArtifactCursor {
results: [Artifact!]!
cursor: Cursor
@@ 208,7 232,7 @@ type ACL {
mode: AccessMode
}
-# Arbitrary file attached to a git repository
+"Arbitrary file attached to a git repository"
type Artifact {
id: Int!
created: Time!
@@ 237,7 261,7 @@ interface Object {
type: ObjectType!
id: String!
shortId: String!
- # Raw git object, base64 encoded
+ "Raw git object, base64 encoded"
raw: String!
}
@@ 275,7 299,7 @@ type TreeEntry {
id: String!
name: String!
object: Object!
- # Unix-style file mode, i.e. 0755 or 0644 (octal)
+ "Unix-style file mode, i.e. 0755 or 0644 (octal)"
mode: Int!
}
@@ 315,41 339,47 @@ type Tag implements Object {
}
input Filter {
- # Number of results to return.
+ "Number of results to return."
count: Int = 20
- # Search terms. The exact meaning varies by usage, but generally these are
- # compatible with the web UI's search syntax.
+ """
+ Search terms. The exact meaning varies by usage, but generally these are
+ compatible with the web UI's search syntax.
+ """
search: String
}
type Query {
- # Returns API version information.
+ "Returns API version information."
version: Version!
- # Returns the authenticated user.
+ "Returns the authenticated user."
me: User! @access(scope: PROFILE, kind: RO)
- # Returns a specific user.
+ "Returns a specific user."
user(username: String!): User @access(scope: PROFILE, kind: RO)
- # Returns repositories that the authenticated user has access to.
- #
- # NOTE: in this version of the API, only repositories owned by the
- # authenticated user are returned, but in the future the default behavior
- # will be to return all repositories that the user either (1) has been given
- # explicit access to via ACLs or (2) has implicit access to either by
- # ownership or group membership.
+ """
+ Returns repositories that the authenticated user has access to.
+
+ NOTE: in this version of the API, only repositories owned by the
+ authenticated user are returned, but in the future the default behavior
+ will be to return all repositories that the user either (1) has been given
+ explicit access to via ACLs or (2) has implicit access to either by
+ ownership or group membership.
+ """
repositories(cursor: Cursor, filter: Filter): RepositoryCursor @access(scope: REPOSITORIES, kind: RO)
- # Returns a specific repository by ID.
+ "Returns a specific repository by ID."
repository(id: Int!): Repository @access(scope: REPOSITORIES, kind: RO)
- # Returns a specific repository, owned by the authenticated user.
+ "Returns a specific repository, owned by the authenticated user."
repositoryByName(name: String!): Repository @access(scope: REPOSITORIES, kind: RO)
- # Returns a specific repository, owned by the given canonical name (e.g.
- # "~sircmpwn").
+ """
+ Returns a specific repository, owned by the given canonical name (e.g.
+ "~sircmpwn").
+ """
repositoryByOwner(owner: String!, repo: String!): Repository @access(scope: REPOSITORIES, kind: RO)
}
@@ 360,32 390,36 @@ input RepoInput {
description: String
visibility: Visibility
- # Updates the custom README associated with this repository. Note that the
- # provided HTML will be sanitized when displayed on the web; see
- # https://man.sr.ht/markdown/#post-processing
+ """
+ Updates the custom README associated with this repository. Note that the
+ provided HTML will be sanitized when displayed on the web; see
+ https://man.sr.ht/markdown/#post-processing
+ """
readme: String
}
type Mutation {
- # Creates a new git repository
+ "Creates a new git repository"
createRepository(name: String!, visibility: Visibility!, description: String): Repository @access(scope: REPOSITORIES, kind: RW)
- # Updates the metadata for a git repository
+ "Updates the metadata for a git repository"
updateRepository(id: Int!, input: RepoInput!): Repository @access(scope: REPOSITORIES, kind: RW)
- # Deletes a git repository
+ "Deletes a git repository"
deleteRepository(id: Int!): Repository @access(scope: REPOSITORIES, kind: RW)
- # Adds or updates a user in the access control list
+ "Adds or updates a user in the access control list"
updateACL(repoId: Int!, mode: AccessMode!, entity: ID!): ACL! @access(scope: ACLS, kind: RW)
- # Deletes an entry from the access control list
+ "Deletes an entry from the access control list"
deleteACL(id: Int!): ACL @access(scope: ACLS, kind: RW)
- # Uploads an artifact. revspec must match a specific git tag, and the
- # filename must be unique among artifacts for this repository.
+ """
+ Uploads an artifact. revspec must match a specific git tag, and the
+ filename must be unique among artifacts for this repository.
+ """
uploadArtifact(repoId: Int!, revspec: String!, file: Upload!): Artifact! @access(scope: OBJECTS, kind: RW)
- # Deletes an artifact.
+ "Deletes an artifact."
deleteArtifact(id: Int!): Artifact @access(scope: OBJECTS, kind: RW)
}