Repository: go-raml/raml Branch: v0 Commit: acaca0c23916 Files: 34 Total size: 987.8 KB Directory structure: gitextract_6fpllo2o/ ├── .gitignore ├── .travis.yml ├── CONTRIBUTORS ├── LICENSE ├── README.md ├── errors.go ├── parser.go ├── raml_test.go ├── samples/ │ ├── bad_raml.raml │ ├── congo/ │ │ └── api.raml │ ├── example.raml │ ├── github/ │ │ └── github-api-v3.raml │ ├── notes/ │ │ └── api.raml │ ├── other_example.raml │ ├── raml-tutorial-200/ │ │ ├── README.md │ │ ├── jukebox-api.raml │ │ ├── jukebox-include-album-new.sample │ │ ├── jukebox-include-album-retrieve.sample │ │ ├── jukebox-include-album-songs.sample │ │ ├── jukebox-include-album.schema │ │ ├── jukebox-include-albums.sample │ │ ├── jukebox-include-artist-albums.sample │ │ ├── jukebox-include-artist-new.sample │ │ ├── jukebox-include-artist-retrieve.sample │ │ ├── jukebox-include-artist.schema │ │ ├── jukebox-include-artists.sample │ │ ├── jukebox-include-song-new.sample │ │ ├── jukebox-include-song-retrieve.sample │ │ ├── jukebox-include-song.schema │ │ └── jukebox-include-songs.sample │ ├── sample_documentation.yaml │ └── simple_example.raml ├── types.go └── validator.go ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ # Compiled Object files, Static and Dynamic libs (Shared Objects) *.o *.a *.so # Folders _obj _test # Architecture specific extensions/prefixes *.[568vq] [568vq].out *.cgo1.go *.cgo2.c _cgo_defun.c _cgo_gotypes.go _cgo_export.* _testmain.go *.exe *.test *.prof ================================================ FILE: .travis.yml ================================================ language: go go: - 1.6.3 - 1.7.1 - tip script: - go test -v ./... ================================================ FILE: CONTRIBUTORS ================================================ go-raml Contributor List (ordered by date): Alon Diamant [https://github.com/advance512] Dvir Volk [https://github.com/dvirsky] If anyone is missing, please message me. ================================================ FILE: LICENSE ================================================ Copyright 2014 DoAT. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTIES WHATSOEVER. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL DoAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of DoAT. ================================================ FILE: README.md ================================================ [![Build Status](https://travis-ci.org/go-raml/raml.svg?branch=v0)](https://travis-ci.org/go-raml/raml) Looking for active maintainers! =============================== -- raml ==== An implementation of a RAML parser for Go. Compliant with RAML 0.8. Introduction ============ RAML is a YAML-based language that describes RESTful APIs. Together with the YAML specification, this specification provides all the information necessary to describe RESTful APIs; to create API client-code and API server-code generators; and to create API user documentation from RAML API definitions. The **_raml_** package enables Go programs to parse RAML files and valid RAML API definitions. It was originally developed within [EverythingMe](https://www.everything.me). Status ------ The **_raml_** package is currently unstable and does not offer any kind of API stability guarantees. Installation ============ The yaml package may be installed by running: $ go get gopkg.in/raml.v0 Opening that same URL in a browser will present a nice introductory page containing links to the documentation, source code, and all versions available for the given package: https://gopkg.in/raml.v0 The actual implementation of the package is in GitHub: https://github.com/go-raml/raml Contributing to development --------------------------- Typical installation process for developing purposes: $ git clone git@github.com:go-raml/raml.git $ cd raml $ go build $ go install $ go test Usage ===== Usage is very simple: package main import ( "fmt" raml "gopkg.in/raml.v0" "github.com/kr/pretty" ) func main() { fileName := "./samples/congo/api.raml" if apiDefinition, err := raml.ParseFile(fileName); err != nil { fmt.Printf("Failed parsing RAML file %s:\n %s", fileName, err.Error()) } else { fmt.Printf("Successfully parsed RAML file %s!\n\n", fileName) pretty.Printf(apiDefinition) } } Getting help ============ * Look up the [RAML 0.8](http://raml.org/spec.html) spec if in doubt * Contact Alon, the maintainer, directly: diamant.alon@gmail.com Roadmap ======= TBD. Reporting Bugs and Contributing Code ==================================== * Want to report a bug or request a feature? Please open [an issue](https://github.com/go-raml/raml/issues/new). * Want to contribute to **_raml_**? Fork the project and make a pull request. Cool cool cool. ## License See [LICENSE](https://github.com/go-raml/raml/blob/v0/LICENSE) file. ================================================ FILE: errors.go ================================================ // Copyright 2014 DoAT. All rights reserved. // // Redistribution and use in source and binary forms, with or without modification, // are permitted provided that the following conditions are met: // // 1. Redistributions of source code must retain the above copyright notice, // this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright notice, // this list of conditions and the following disclaimer in the documentation and/or // other materials provided with the distribution. // // THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTIES WHATSOEVER. // ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, // THE IMPLIED WARRANTIES OF NON INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A // PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL DoAT OR CONTRIBUTORS // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, // EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // The views and conclusions contained in the software and documentation are those of // the authors and should not be interpreted as representing official policies, // either expressed or implied, of DoAT. package raml // This file contains all code related to YAML and RAML errors. import ( "fmt" "strings" yaml "github.com/advance512/yaml" ) // A RamlError is returned by the ParseFile function when RAML or YAML problems // are encountered when parsing the RAML document. type RamlError struct { Errors []string } func (e *RamlError) Error() string { return fmt.Sprintf("Error parsing RAML:\n %s\n", strings.Join(e.Errors, "\n ")) } // Populate the RAML error value with converted YAML error strings (with // additional context) func populateRAMLError(ramlError *RamlError, yamlErrors *yaml.TypeError) { // Go over the errors for _, currErr := range yamlErrors.Errors { // Create the RAML errors ramlError.Errors = append(ramlError.Errors, convertYAMLError(currErr)) } } // Convert a YAML error string into RAML error string, with more context func convertYAMLError(yamlError string) string { if strings.Contains(yamlError, "cannot unmarshal") { yamlErrorParts := strings.Split(yamlError, " ") if len(yamlErrorParts) >= 7 { fmt.Println(yamlError) var ok bool var source string var target string var targetName string line := yamlErrorParts[1] line = line[:len(line)-1] // TODO: support more complex types: // map[string]raml.NamedParameter --> // detect map, format to: // "mapping of %s to %s", ramlTypeNames["string"], ramlTypeNames["raml.NamedParameter"] // if "string" is not found, use the key, i.e. "string" in this case. // so the output would be: // mapping of string to named parameter // TODO: instead of having string in the key of some mappings, // perhaps use a type alias: // type Name string // map[Name]NamedParameter // would output: // mapping of name string to named parameter if source, ok = yamlTypeToName[yamlErrorParts[4]]; !ok { source = yamlErrorParts[4] } fmt.Println("source: ", source) if source == "string" { source = fmt.Sprintf("string (got %s)", yamlErrorParts[5]) target = yamlErrorParts[7] } else { target = yamlErrorParts[6] } if targetName, ok = ramlTypeNames[target]; !ok { targetName = target } target, _ = ramlTypes[target] return fmt.Sprintf("line %s: %s cannot be of "+ "type %s, must be %s", line, targetName, source, target) } } // Otherwise return fmt.Sprintf("YAML error, %s", yamlError) } var yamlTypeToName map[string]string = map[string]string{ "!!seq": "sequence", "!!map": "mapping", "!!int": "integer", "!!str": "string", "!!null": "null", "!!bool": "boolean", "!!float": "float", "!!timestamp": "timestamp", "!!binary": "binary", "!!merge": "merge", } var ramlTypeNames map[string]string = map[string]string{ "string": "string value", "int": "numeric value", "raml.NamedParameter": "named parameter", "raml.HTTPCode": "HTTP code", "raml.HTTPHeader": "HTTP header", "raml.Header": "header", "raml.Documentation": "documentation", "raml.Body": "body", "raml.Response": "response", "raml.DefinitionParameters": "definition parameters", "raml.DefinitionChoice": "definition choice", "raml.Trait": "trait", "raml.ResourceTypeMethod": "resource type method", "raml.ResourceType": "resource type", "raml.SecuritySchemeMethod": "security scheme method", "raml.SecurityScheme": "security scheme", "raml.Method": "method", "raml.Resource": "resource", "raml.APIDefinition": "API definition", } var ramlTypes map[string]string = map[string]string{ "string": "string", "int": "integer", "raml.NamedParameter": "mapping", "raml.HTTPCode": "integer", "raml.HTTPHeader": "string", "raml.Header": "mapping", "raml.Documentation": "mapping", "raml.Body": "mapping", "raml.Response": "mapping", "raml.DefinitionParameters": "mapping", "raml.DefinitionChoice": "string or mapping", "raml.Trait": "mapping", "raml.ResourceTypeMethod": "mapping", "raml.ResourceType": "mapping", "raml.SecuritySchemeMethod": "mapping", "raml.SecurityScheme": "mapping", "raml.Method": "mapping", "raml.Resource": "mapping", "raml.APIDefinition": "mapping", } ================================================ FILE: parser.go ================================================ // Copyright 2014 DoAT. All rights reserved. // // Redistribution and use in source and binary forms, with or without modification, // are permitted provided that the following conditions are met: // // 1. Redistributions of source code must retain the above copyright notice, // this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright notice, // this list of conditions and the following disclaimer in the documentation and/or // other materials provided with the distribution. // // THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTIES WHATSOEVER. // ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, // THE IMPLIED WARRANTIES OF NON INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A // PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL DoAT OR CONTRIBUTORS // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, // EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // The views and conclusions contained in the software and documentation are those of // the authors and should not be interpreted as representing official policies, // either expressed or implied, of DoAT. package raml // This file contains all of the RAML parser related code. import ( "bufio" "bytes" "errors" "fmt" "io" "io/ioutil" "path/filepath" "strings" yaml "github.com/advance512/yaml" ) // Parse a RAML file. Returns a raml.APIDefinition value or an error if // everything is something went wrong. // This is the main entry point to the RAML parser. func ParseFile(filePath string) (*APIDefinition, error) { // Get the working directory workingDirectory, fileName := filepath.Split(filePath) // Read original file contents into a byte array mainFileBytes, err := readFileContents(workingDirectory, fileName) if err != nil { return nil, err } // Get the contents of the main file mainFileBuffer := bytes.NewBuffer(mainFileBytes) // Verify the YAML version var ramlVersion string if firstLine, err := mainFileBuffer.ReadString('\n'); err != nil { return nil, fmt.Errorf("Problem reading RAML file (Error: %s)", err.Error()) } else { // We read some data... if len(firstLine) >= 10 { ramlVersion = firstLine[:10] } // TODO: Make this smart. We probably won't support multiple RAML // versions in the same package - we'll have different branches // for different versions. This one is hard-coded to 0.8. // Still, would be good to think about this. if ramlVersion != "#%RAML 0.8" { return nil, errors.New("Input file is not a RAML 0.8 file. Make " + "sure the file starts with #%RAML 0.8") } } // Pre-process the original file, following !include directive preprocessedContentsBytes, err := preProcess(mainFileBuffer, workingDirectory) if err != nil { return nil, fmt.Errorf("Error preprocessing RAML file (Error: %s)", err.Error()) } //pretty.Println(string(preprocessedContentsBytes)) // Unmarshal into an APIDefinition value apiDefinition := new(APIDefinition) apiDefinition.RAMLVersion = ramlVersion // Go! err = yaml.Unmarshal(preprocessedContentsBytes, apiDefinition) // Any errors? if err != nil { // Create a RAML error value ramlError := new(RamlError) // Copy the YAML errors into it.. if yamlErrors, ok := err.(*yaml.TypeError); ok { populateRAMLError(ramlError, yamlErrors) } else { // Or just any other error, though this shouldn't happen. ramlError.Errors = append(ramlError.Errors, err.Error()) } return nil, ramlError } // Good. return apiDefinition, nil } // Reads the contents of a file, returns a bytes buffer func readFileContents(workingDirectory string, fileName string) ([]byte, error) { filePath := filepath.Join(workingDirectory, fileName) if fileName == "" { return nil, fmt.Errorf("File name cannot be nil: %s", filePath) } // Read the file fileContentsArray, err := ioutil.ReadFile(filePath) if err != nil { return nil, fmt.Errorf("Could not read file %s (Error: %s)", filePath, err.Error()) } return fileContentsArray, nil } // preProcess acts as a preprocessor for a RAML document in YAML format, // including files referenced via !include. It returns a pre-processed document. func preProcess(originalContents io.Reader, workingDirectory string) ([]byte, error) { // NOTE: Since YAML doesn't support !include directives, and since go-yaml // does NOT play nice with !include tags, this has to be done like this. // I am considering modifying go-yaml to add custom handlers for specific // tags, to add support for !include, but for now - this method is // GoodEnough(TM) and since it will only happen once, I am not prematurely // optimizing it. var preprocessedContents bytes.Buffer // Go over each line, looking for !include tags scanner := bufio.NewScanner(originalContents) var line string // Scan the file until we reach EOF or error out for scanner.Scan() { line = scanner.Text() // Did we find an !include directive to handle? if idx := strings.Index(line, "!include"); idx != -1 { // TODO: Do this better includeLength := len("!include ") includedFile := line[idx+includeLength:] preprocessedContents.Write([]byte(line[:idx])) // Get the included file contents includedContents, err := readFileContents(workingDirectory, includedFile) if err != nil { return nil, fmt.Errorf("Error including file %s:\n %s", includedFile, err.Error()) } // TODO: Check that you only insert .yaml, .raml, .txt and .md files // In case of .raml or .yaml, remove the comments // In case of other files, Base64 them first. // TODO: Better, step by step checks .. though prolly it'll panic // Write text files in the same indentation as the first line internalScanner := bufio.NewScanner(bytes.NewBuffer(includedContents)) // Indent by this much firstLine := true indentationString := "" // Go over each line, write it for internalScanner.Scan() { internalLine := internalScanner.Text() preprocessedContents.WriteString(indentationString) if firstLine { indentationString = strings.Repeat(" ", idx) firstLine = false } preprocessedContents.WriteString(internalLine) preprocessedContents.WriteByte('\n') } } else { // No, just a simple line.. write it preprocessedContents.WriteString(line) preprocessedContents.WriteByte('\n') } } // Any errors encountered? if err := scanner.Err(); err != nil { return nil, fmt.Errorf("Error reading YAML file: %s", err.Error()) } // Return the preprocessed contents return preprocessedContents.Bytes(), nil } ================================================ FILE: raml_test.go ================================================ // Copyright 2014 DoAT. All rights reserved. // // Redistribution and use in source and binary forms, with or without modification, // are permitted provided that the following conditions are met: // // 1. Redistributions of source code must retain the above copyright notice, // this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright notice, // this list of conditions and the following disclaimer in the documentation and/or // other materials provided with the distribution. // // THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTIES WHATSOEVER. // ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, // THE IMPLIED WARRANTIES OF NON INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A // PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL DoAT OR CONTRIBUTORS // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, // EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // The views and conclusions contained in the software and documentation are those of // the authors and should not be interpreted as representing official policies, // either expressed or implied, of DoAT. package raml // This file contains tests. import ( "fmt" "testing" ) // TODO: Way, way more serious tests. // // Inspirations: // https://github.com/raml-org/raml-js-parser/tree/master/test // https://github.com/raml-org/raml-java-parser/tree/master/src/test // https://github.com/an2deg/pyraml-parser/tree/master/tests // https://github.com/cybertk/ramlev/tree/master/test/fixtures func TestFailedParsing(t *testing.T) { fileNames := []string{"./samples/bad_raml.raml"} for _, fileName := range fileNames { fmt.Printf("Attempting to parse RAML file: %s\n", fileName) _, err := ParseFile(fileName) if err == nil { t.Fatalf("Failed detecting bad RAML file %s", fileName) } else { fmt.Printf("Detected bad RAML file %s:\n%s", fileName, err.Error()) } } } func TestParsing(t *testing.T) { fileNames := []string{"./samples/example.raml", "./samples/simple_example.raml", "./samples/other_example.raml", "./samples/congo/api.raml", "./samples/notes/api.raml", "./samples/github/github-api-v3.raml", "./samples/raml-tutorial-200/jukebox-api.raml"} for _, fileName := range fileNames { fmt.Printf("Attempting to parse RAML file: %s\n", fileName) apiDefinition, err := ParseFile(fileName) if err != nil { t.Fatalf("Failed parsing file %s:\n %s", fileName, err.Error()) } else { fmt.Printf("Successfully parsed file %s!\n", fileName) } if apiDefinition.RAMLVersion != "#%RAML 0.8" { t.Fatalf("Detected erroneous RAML version: %s", apiDefinition.RAMLVersion) } // pretty.Println(apiDefinition) } } ================================================ FILE: samples/bad_raml.raml ================================================ #%RAML 0.8 title: Notes Example API /jobs: displayName: Jobs post: description: Create a job /projects: displayName: Projects post: description: Create a project /resources: displayName: Resources type: searchableCollection: queryParamName: title fallbackParamName: digest_all_fields get: description: Get a resource is: - secured: tokenName: access_token paged: maxPages: 10 post: description: Post a resource /{resourceId}: get: description: Get a resource ID put: description: Put resource ID delete: description: Delete a resource ID /yet_another: get: description: Yet another uriParameters: communityDomain: displayName: Community Domain type: string communityPath: displayName: Community Path type: string pattern: ^[a-zA-Z0-9][-a-zA-Z0-9]*$ minLength: "hello" baseUri: /lala protocols: [HTTP, HTTPS] traits: - secured: queryParameters: <>: description: A valid <> is required paged: queryParameters: numPages: description: The number of pages to return, not to exceed <> resourceTypes: - rttest: description: test - one: description: hi - auditableResource: post?: body: application/x-www-form-urlencoded: formParameters: createAuthority: description: | If the resource has a post method defined, expect a createAuthority property in its body delete?: body: multipart/form-data: formParameters: deleteAuthority: description: | If the resource has a delete method defined, expect a deleteAuthority property in its body - searchableCollection: get: queryParameters: <>: description: Return <> that have their <> matching the given value <>: description: If no values match the value given for <>, use <> instead securitySchemes: - oauth_2_0: description: | Dropbox supports OAuth 2.0 for authenticating all API requests. type: OAuth 2.0 describedBy: headers: Authorization: description: | Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter. type: string queryParameters: access_token: description: | Used to send a valid OAuth 2 access token. Do not use together with the "Authorization" header type: string responses: 401: description: | Bad or expired token. This can happen if the user or Dropbox revoked or expired an access token. To fix, you should re- authenticate the user. 403: description: | Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...). Unfortunately, re-authenticating the user won't help here. settings: authorizationUri: https://www.dropbox.com/1/oauth2/authorize accessTokenUri: https://api.dropbox.com/1/oauth2/token authorizationGrants: [ code, token ] - oauth_1_0: description: | OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. type: OAuth 1.0 settings: requestTokenUri: https://api.dropbox.com/1/oauth/request_token authorizationUri: https://www.dropbox.com/1/oauth/authorize tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token - customHeader: description: | A custom ================================================ FILE: samples/congo/api.raml ================================================ #%RAML 0.8 title: Congo API For Drone Deliveries mediaType: application/json /deliveries: get: description: Get a list of deliveries queryParameters: sinceDate: type: date example: Mon, 14 Jul 2014 07:00:00 GMT throughDate: type: date example: Mon, 18 Jul 2014 07:00:00 GMT responses: 200: body: example: | [ { "id": "4", "at": "Tue, 08 Jul 2014 13:00:00 GMT", "toAddressId": "gi6w4fgi", "orderItemId": "6782798", "status": "completed", "droneId": "f" }, { "id": "137", "at": "Sun, 20 Jul 2014 19:36:00 GMT", "toAddressId": "6tg23d6i", "orderItemId": "7626827", "status": "scheduled", "droneId": "a" }, { "id": "8", "at": "Sun, 20 Jul 2014 21:20:00 GMT", "toAddressId": "gi6w4fgi", "orderItemId": "9877292", "status": "scheduled", "droneId": "f" } ] post: description: Create/request a new delivery body: example: | { "at": "Sun, 20 Jul 2014 21:20:00 GMT", "toAddressId": "273hh79", "orderItemId": "736786" } responses: 201: headers: Location: body: example: | { "id": "987", "at": "Sun, 20 Jul 2014 21:20:00 GMT", "toAddressId": "273hh79", "orderItemId": "736786", "status": "scheduled", "droneId": "f" } /{deliveryId}: get: description: Get information on a specific delivery responses: 200: body: example: | { "id": "8", "at": "Sun, 20 Jul 2014 21:20:00 GMT", "toAddressId": "gi6w4fgi", "orderItemId": "736786", "status": "scheduled", "droneId": "f" } patch: description: Update the information on a specific delivery body: example: | { "at": "Mon, 21 Jul 2014 00:00:00 GMT" } responses: 200: body: example: | { "id": "8", "at": "Mon, 21 Jul 2014 00:00:00 GMT", "toAddressId": "gi6w4fgi", "orderItemId": "736786", "status": "scheduled", "droneId": "f" } delete: description: Cancel a specific delivery responses: 204: /drones: get: description: Get a list of drones queryParameters: atLatitude: description: Latitude in decimal degrees type: number example: 37.8 atLongitude: description: Longitude in decimal degrees type: number example: -122.3 atAltitude: description: Altitude in meters above the [ellipsoid](http://www.w3.org/TR/geolocation-API/#ref-wgs) type: number example: 0 atRange: description: Maximum distance from location, in meters type: number example: 50 default: 100 responses: 200: body: example: | [ { "id": "a", "latitude": 37.787862, "longitude": -122.404694, "altitude": 28.3, "name": "High Flyer" }, { "id": "f", "latitude": 37.852519, "longitude": -122.237390, "altitude": 56.9, "name": "Camelot" } ] post: description: Add a new drone to the fleet body: example: | { "name": "Lancelot" } /{droneId}: get: description: Get information on a specific drone responses: 200: body: example: | { "id": "f", "latitude": 37.852519, "longitude": -122.237390, "altitude": 56.9, "name": "Camelot" } patch: description: Update the information on a specific drone body: example: | { "name": "Arthur" } responses: 200: body: example: | { "id": "f", "latitude": 37.852519, "longitude": -122.237390, "altitude": 56.9, "name": "Arthur" } delete: description: Remove a drone from the fleet responses: 204: /deliveries: get: description: The deliveries scheduled for the current drone responses: 200: body: example: | [ { "id": "8", "at": "Sun, 20 Jul 2014 21:20:00 GMT", "toAddressId": "gi6w4fgi", "orderItemId": "736786", "status": "scheduled", "droneId": "f" } ] ================================================ FILE: samples/example.raml ================================================ #%RAML 0.8 --- title: Example API baseUri: http://example.com securitySchemes: - basic: type: Basic Authentication traits: - secured: description: Some requests require authentication - unsecured: description: This is not secured - catpictures: description: requires cat headers - anotherTrait: {} - andAnotherTrait: {} - andYetAnotherTrait: {} - aFinalTrait: {} - someParameterizedTrait: description: <> resourceTypes: - collection: description: bunk documentation: - title: Getting Started content: | # Header Content ## Subheader **Bolded content** /resource: displayName: First One is: [ secured ] options: connect: trace: patch: delete: put: get: description: get the first one headers: x-custom: /{resourceId}: description: This is a resource description *with* some _markdown_ embedded in it uriParameters: resourceId: required: true description: Which resoure would you like to view get: description: | Instagram’s API uses the [OAuth 2.0 protocol](http://tools.ietf.org/html/draft-ietf-oauth-v2-12) for simple, but effective authentication and authorization. OAuth 2.0 is much easier to use than previous schemes; developers can start using the Instagram API almost immediately. The one thing to keep in mind is that all requests to the API must be made over SSL (https:// not http://) ## Do you need to authenticate? For the most part, Instagram’s API only requires the use of a _client_id). A client_id simply associates your server, script, or program with a specific application. However, some requests require authentication - specifically requests made on behalf of a user. Authenticated requests require an _access_token_. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future. Note that in many situations, you may not need to authenticate users at all. For instance, you may request popular photos without authenticating (i.e. you do not need to provide an access_token; just use your client ID with your request). We only require authentication in cases where your application is making requests on behalf of a user (commenting, liking, browsing a user’s feed, etc.). ## Receiving an access_token queryParameters: filter: description: What to filter type: string post: body: application/json: application/x-www-form-urlencoded: formParameters: name: description: The name of the resource to create type: string example: Comment description: description: A description of the resource to create type: string example: User-generated content pertinent to the associated blog post multipart/form-data: formParameters: name: description: The name of the resource to create type: string example: Comment description: description: A description of the resource to create type: string example: User-generated content pertinent to the associated blog post /another/resource: displayName: Cats type: collection is: [secured, catpictures] connect: !!null head: !!null get: queryParameters: chunk: displayName: page description: Which page to display type: integer example: 1 minimum: 1 maximum: 100 required: true order: description: The sort order of resources type: string enum: ["oldest", "newest"] example: oldest minLength: 5 maxLength: 7 default: newest query: description: A query parameter repeat: true /resource-with-headers: displayName: Resource With headers get: headers: x-custom-header: displayName: Custom header description: This header is used to send data that... type: string pattern: ^\w+$ x-p-{*}: displayName: Parameterized header /secured-resource: displayName: SO SECURE get: securedBy: [basic] /resource-with-method-level-traits: displayName: First One is: [secured] get: is: [unsecured, catpictures, anotherTrait, andAnotherTrait, andYetAnotherTrait, aFinalTrait, someParameterizedTrait: { someParameterName: someParameterValue }, otherParameterizedTrait : {asd: 123}] description: get the first one /resource-with-form-and-multipart-form-parameters: get: queryParameters: some_query_param: displayName: Some Query Param description: Your value for some thing. type: string required: true example: "my value" body: application/json: example: | { "api_key": "c4f820f0420a013ea143230c290fbf99", ... } application/x-www-form-urlencoded: formParameters: api_key: displayName: API Key description: Your license key for the application. Please contact developer@nzpost.co.nz for a license key type: string required: true example: "c4f820f0420a013ea143230c290fbf99" multipart/form-data: formParameters: api_key: displayName: API Key description: Your license key for the application. Please contact developer@nzpost.co.nz for a license key type: string required: true example: "c4f820f0420a013ea143230c290fbf99" ================================================ FILE: samples/github/github-api-v3.raml ================================================ #%RAML 0.8 --- title: GitHub API version: v3 baseUri: https://api.github.com/ securitySchemes: - oauth_2_0: description: | OAuth2 is a protocol that lets external apps request authorization to private details in a user's GitHub account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time. type: OAuth 2.0 describedBy: headers: Authorization: description: | Used to send a valid OAuth 2 access token. Do not use together with the "access_token" query string parameter. type: string queryParameters: access_token: description: | Used to send a valid OAuth 2 access token. Do not use together with the "Authorization" header type: string responses: 404: description: Unauthorized settings: authorizationUri: https://github.com/login/oauth/authorize accessTokenUri: https://github.com/login/oauth/access_token authorizationGrants: [ code ] scopes: - "user" - "user:email" - "user:follow" - "public_repo" - "repo" - "repo:status" - "delete_repo" - "notifications" - "gist" securedBy: [ oauth_2_0 ] mediaType: application/json resourceTypes: - base: get?: &common headers: X-GitHub-Media-Type: description: | You can check the current version of media type in responses. type: string Accept: description: Is used to set specified media type. type: string X-RateLimit-Limit: type: integer X-RateLimit-Remaining: type: integer X-RateLimit-Reset: type: integer X-GitHub-Request-Id: type: integer responses: 403: description: | API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting for details. post?: *common patch?: *common put?: *common delete?: *common - item: type: base get?: post?: patch?: put?: delete?: responses: 204: description: Item removed. - collection: type: base get?: post?: traits: - historical: queryParameters: since: description: | Timestamp in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned. type: string - filterable: queryParameters: filter: description: | Issues assigned to you / created by you / mentioning you / you're subscribed to updates for / All issues the authenticated user can see enum: - assigned - created - mentioned - subscribed - all default: all required: true state: enum: - open - closed default: open required: true labels: description: String list of comma separated Label names. Example - bug,ui,@high. type: string required: true sort: enum: - created - updated - comments default: created required: true direction: enum: - asc - desc default: desc required: true since: description: | Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only issues updated at or after this time are returned. type: string # Search /search: /repositories: type: collection get: description: Search repositories. queryParameters: q: description: | The search terms. This can be any combination of the supported repository search parameters: 'Search In' Qualifies which fields are searched. With this qualifier you can restrict the search to just the repository name, description, readme, or any combination of these. 'Size' Finds repositories that match a certain size (in kilobytes). 'Forks' Filters repositories based on the number of forks, and/or whether forked repositories should be included in the results at all. 'Created' and 'Last Updated' Filters repositories based on times of creation, or when they were last updated. 'Users or Repositories' Limits searches to a specific user or repository. 'Languages' Searches repositories based on the language they're written in. 'Stars' Searches repositories based on the number of stars. type: string required: true sort: description: If not provided, results are sorted by best match. enum: - stars - forks - updated order: enum: - asc - desc default: desc responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "items": [ { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "received_events_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "private": { "type": "boolean" }, "html_url": { "type": "string" }, "description": { "type": "string" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "homepage": { "type": "string" }, "size": { "type": "integer" }, "watchers_count": { "type": "integer" }, "language": { "type": "string" }, "forks_count": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "forks": { "type": "integer" }, "open_issues": { "type": "integer" }, "watchers": { "type": "integer" }, "master_branch": { "type": "string" }, "default_branch": { "type": "string" }, "score": { "type": "number" } }, "type": "object" } ], "type": "array" } } example: | { "total_count": 40, "items": [ { "id": 3081286, "name": "Tetris", "full_name": "dtrupenn/Tetris", "owner": { "login": "dtrupenn", "id": 872147, "avatar_url": "https://secure.gravatar.com/avatar/e7956084e75f239de85d3a31bc172ace?d=https://a248.e.akamai.net/assets.github.com/images/gravatars/gravatar-user-420.png", "gravatar_id": "e7956084e75f239de85d3a31bc172ace", "url": "https://api.github.com/users/dtrupenn", "received_events_url": "https://api.github.com/users/dtrupenn/received_events", "type": "User" }, "private": false, "html_url": "https://github.com/dtrupenn/Tetris", "description": "A C implementation of Tetris using Pennsim through LC4", "fork": false, "url": "https://api.github.com/repos/dtrupenn/Tetris", "created_at": "2012-01-01T00:31:50Z", "updated_at": "2013-01-05T17:58:47Z", "pushed_at": "2012-01-01T00:37:02Z", "homepage": "", "size": 524, "watchers_count": 1, "language": "Assembly", "forks_count": 0, "open_issues_count": 0, "forks": 0, "open_issues": 0, "watchers": 1, "master_branch": "master", "default_branch": "master", "score": 10.309712 } ] } /code: type: collection get: description: Search code. queryParameters: q: description: | The search terms. This can be any combination of the supported code search parameters: 'Search In' Qualifies which fields are searched. With this qualifier you can restrict the search to just the file contents, the file path, or both. 'Languages' Searches code based on the language it's written in. 'Forks' Filters repositories based on the number of forks, and/or whether code from forked repositories should be included in the results at all. 'Size' Finds files that match a certain size (in bytes). 'Path' Specifies the path that the resulting file must be at. 'Extension' Matches files with a certain extension. 'Users' or 'Repositories' Limits searches to a specific user or repository. type: string required: true sort: description: | Can only be 'indexed', which indicates how recently a file has been indexed by the GitHub search infrastructure. If not provided, results are sorted by best match. enum: - indexed order: enum: - asc - desc default: desc responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "items": [ { "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" }, "git_url": { "type": "string" }, "html_url": { "type": "string" }, "repository": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "followers_url": { "type": "string" }, "following_url": { "type": "string" }, "gists_url": { "type": "string" }, "starred_url": { "type": "string" }, "subscriptions_url": { "type": "string" }, "organizations_url": { "type": "string" }, "repos_url": { "type": "string" }, "events_url": { "type": "string" }, "received_events_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "private": { "type": "boolean" }, "html_url": { "type": "string" }, "description": { "type": "string" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "forks_url": { "type": "string" }, "keys_url": { "type": "string" }, "collaborators_url": { "type": "string" }, "teams_url": { "type": "string" }, "hooks_url": { "type": "string" }, "issue_events_url": { "type": "string" }, "events_url": { "type": "string" }, "assignees_url": { "type": "string" }, "branches_url": { "type": "string" }, "tags_url": { "type": "string" }, "blobs_url": { "type": "string" }, "git_tags_url": { "type": "string" }, "git_refs_url": { "type": "string" }, "trees_url": { "type": "string" }, "statuses_url": { "type": "string" }, "languages_url": { "type": "string" }, "stargazers_url": { "type": "string" }, "contributors_url": { "type": "string" }, "subscribers_url": { "type": "string" }, "subscription_url": { "type": "string" }, "commits_url": { "type": "string" }, "git_commits_url": { "type": "string" }, "comments_url": { "type": "string" }, "issue_comment_url": { "type": "string" }, "contents_url": { "type": "string" }, "compare_url": { "type": "string" }, "merges_url": { "type": "string" }, "archive_url": { "type": "string" }, "downloads_url": { "type": "string" }, "issues_url": { "type": "string" }, "pulls_url": { "type": "string" }, "milestones_url": { "type": "string" }, "notifications_url": { "type": "string" }, "labels_url": { "type": "string" } }, "type": "object" }, "score": { "type": "number" } }, "type": "object" } ], "type": "array" } } example: | { "total_count": 104, "items": [ { "name": "github-issue-importer.gemspec", "path": "github-issue-importer.gemspec", "sha": "394508202991504d8a0771ae027454facaaa045a", "url": "https://api.github.com/repositories/1586630/contents/github-issue-importer.gemspec?ref=aa22a4be513163c73531e96bd99f4b49d6ded8a6", "git_url": "https://api.github.com/repositories/1586630/git/blobs/394508202991504d8a0771ae027454facaaa045a", "html_url": "https://github.com/johnf/github-issue-importer/blob/aa22a4be513163c73531e96bd99f4b49d6ded8a6/github-issue-importer.gemspec", "repository": { "id": 1586630, "name": "github-issue-importer", "full_name": "johnf/github-issue-importer", "owner": { "login": "johnf", "id": 42590, "avatar_url": "https://secure.gravatar.com/avatar/ab4d879ba3233a270aa14f447c795505?d=https://a248.e.akamai.net/assets.github.com/images/gravatars/gravatar-user-420.png", "gravatar_id": "ab4d879ba3233a270aa14f447c795505", "url": "https://api.github.com/users/johnf", "html_url": "https://github.com/johnf", "followers_url": "https://api.github.com/users/johnf/followers", "following_url": "https://api.github.com/users/johnf/following{/other_user}", "gists_url": "https://api.github.com/users/johnf/gists{/gist_id}", "starred_url": "https://api.github.com/users/johnf/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/johnf/subscriptions", "organizations_url": "https://api.github.com/users/johnf/orgs", "repos_url": "https://api.github.com/users/johnf/repos", "events_url": "https://api.github.com/users/johnf/events{/privacy}", "received_events_url": "https://api.github.com/users/johnf/received_events", "type": "User" }, "private": false, "html_url": "https://github.com/johnf/github-issue-importer", "description": "Import Issues from Launchpad (for now) into github", "fork": false, "url": "https://api.github.com/repos/johnf/github-issue-importer", "forks_url": "https://api.github.com/repos/johnf/github-issue-importer/forks", "keys_url": "https://api.github.com/repos/johnf/github-issue-importer/keys{/key_id}", "collaborators_url": "https://api.github.com/repos/johnf/github-issue-importer/collaborators{/collaborator}", "teams_url": "https://api.github.com/repos/johnf/github-issue-importer/teams", "hooks_url": "https://api.github.com/repos/johnf/github-issue-importer/hooks", "issue_events_url": "https://api.github.com/repos/johnf/github-issue-importer/issues/events{/number}", "events_url": "https://api.github.com/repos/johnf/github-issue-importer/events", "assignees_url": "https://api.github.com/repos/johnf/github-issue-importer/assignees{/user}", "branches_url": "https://api.github.com/repos/johnf/github-issue-importer/branches{/branch}", "tags_url": "https://api.github.com/repos/johnf/github-issue-importer/tags", "blobs_url": "https://api.github.com/repos/johnf/github-issue-importer/git/blobs{/sha}", "git_tags_url": "https://api.github.com/repos/johnf/github-issue-importer/git/tags{/sha}", "git_refs_url": "https://api.github.com/repos/johnf/github-issue-importer/git/refs{/sha}", "trees_url": "https://api.github.com/repos/johnf/github-issue-importer/git/trees{/sha}", "statuses_url": "https://api.github.com/repos/johnf/github-issue-importer/statuses/{sha}", "languages_url": "https://api.github.com/repos/johnf/github-issue-importer/languages", "stargazers_url": "https://api.github.com/repos/johnf/github-issue-importer/stargazers", "contributors_url": "https://api.github.com/repos/johnf/github-issue-importer/contributors", "subscribers_url": "https://api.github.com/repos/johnf/github-issue-importer/subscribers", "subscription_url": "https://api.github.com/repos/johnf/github-issue-importer/subscription", "commits_url": "https://api.github.com/repos/johnf/github-issue-importer/commits{/sha}", "git_commits_url": "https://api.github.com/repos/johnf/github-issue-importer/git/commits{/sha}", "comments_url": "https://api.github.com/repos/johnf/github-issue-importer/comments{/number}", "issue_comment_url": "https://api.github.com/repos/johnf/github-issue-importer/issues/comments/{number}", "contents_url": "https://api.github.com/repos/johnf/github-issue-importer/contents/{ path}", "compare_url": "https://api.github.com/repos/johnf/github-issue-importer/compare/{base}...{head}", "merges_url": "https://api.github.com/repos/johnf/github-issue-importer/merges", "archive_url": "https://api.github.com/repos/johnf/github-issue-importer/{archive_format}{/ref}", "downloads_url": "https://api.github.com/repos/johnf/github-issue-importer/downloads", "issues_url": "https://api.github.com/repos/johnf/github-issue-importer/issues{/number}", "pulls_url": "https://api.github.com/repos/johnf/github-issue-importer/pulls{/number}", "milestones_url": "https://api.github.com/repos/johnf/github-issue-importer/milestones{/number}", "notifications_url": "https://api.github.com/repos/johnf/github-issue-importer/notifications{?since,all,participating}", "labels_url": "https://api.github.com/repos/johnf/github-issue-importer/labels{/name}" }, "score": 0.96691436 } ] } /users: type: collection get: description: Search users. queryParameters: q: description: | The search terms. This can be any combination of the supported user search parameters: 'Search In' Qualifies which fields are searched. With this qualifier you can restrict the search to just the username, public email, full name, location, or any combination of these. 'Repository count' Filters users based on the number of repositories they have. 'Location' Filter users by the location indicated in their profile. 'Language' Search for users that have repositories that match a certain language. 'Created' Filter users based on when they joined. 'Followers' Filter users based on the number of followers they have. type: string required: true sort: description: If not provided, results are sorted by best match. enum: - followers - repositories - joined order: enum: - asc - desc default: desc responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "items": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "followers_url": { "type": "string" }, "subscriptions_url": { "type": "string" }, "organizations_url": { "type": "string" }, "repos_url": { "type": "string" }, "received_events_url": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "number" } }, "type": "object" } ], "type": "array" } } example: | { "total_count": 12, "items": [ { "login": "mojombo", "id": 1, "avatar_url": "https://secure.gravatar.com/avatar/25c7c18223fb42a4c6ae1c8db6f50f9b?d=https://a248.e.akamai.net/assets.github.com/images/gravatars/gravatar-user-420.png", "gravatar_id": "25c7c18223fb42a4c6ae1c8db6f50f9b", "url": "https://api.github.com/users/mojombo", "html_url": "https://github.com/mojombo", "followers_url": "https://api.github.com/users/mojombo/followers", "subscriptions_url": "https://api.github.com/users/mojombo/subscriptions", "organizations_url": "https://api.github.com/users/mojombo/orgs", "repos_url": "https://api.github.com/users/mojombo/repos", "received_events_url": "https://api.github.com/users/mojombo/received_events", "type": "User", "score": 105.47857 } ] } # Events /events: type: collection get: description: List public events. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] # Feeds /feeds: type: collection get: description: | List Feeds. GitHub provides several timeline resources in Atom format. The Feeds API lists all the feeds available to the authenticating user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "timeline_url": { "type": "string" }, "user_url": { "type": "string" }, "current_user_public": { "type": "string" }, "current_user_url": { "type": "string" }, "current_user_actor_url": { "type": "string" }, "current_user_organization_url": { "type": "string" }, "_links": { "properties": { "timeline": { "properties": { "href": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "user": { "properties": { "href": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "current_user_public": { "properties": { "href": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "current_user": { "properties": { "href": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "current_user_actor": { "properties": { "href": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "current_user_organization": { "properties": { "href": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } } } } example: | { "timeline_url": "https://github.com/timeline", "user_url": "https://github.com/{user}", "current_user_public": "https://github.com/defunkt", "current_user_url": "https://github.com/defunkt.private?token=abc123", "current_user_actor_url": "https://github.com/defunkt.private.actor?token=abc123", "current_user_organization_url": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123", "_links": { "timeline": { "href": "https://github.com/timeline", "type": "application/atom xml" }, "user": { "href": "https://github.com/{user}", "type": "application/atom xml" }, "current_user_public": { "href": "https://github.com/defunkt", "type": "application/atom xml" }, "current_user": { "href": "https://github.com/defunkt.private?token=abc123", "type": "application/atom xml" }, "current_user_actor": { "href": "https://github.com/defunkt.private.actor?token=abc123", "type": "application/atom xml" }, "current_user_organization": { "href": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123", "type": "application/atom xml" } } } # Meta /meta: type: collection get: description: This gives some information about GitHub.com, the service. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "hooks": [ { "description": "An Array of IP addresses in CIDR format specifying the addresses that incoming service hooks will originate from.", "type": "string" } ], "type": "array", "git": [ { "description": "An Array of IP addresses in CIDR format specifying the Git servers at GitHub.", "type": "string" } ] } } example: | { "hooks": [ "127.0.0.1/32" ], "git": [ "127.0.0.1/32" ] } # Rate limit /rate_limit: type: collection get: description: | Get your current rate limit status Note: Accessing this endpoint does not count against your rate limit. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "rate": { "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "reset": { "type": "integer" } } } } } example: | { "rate": { "limit": 5000, "remaining": 4999, "reset": 1372700873 } } # Issues /issues: type: item get: is: [ filterable ] description: | List issues. List all issues across all the authenticated user's visible repositories. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "issues": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } ] # Other /notifications: type: collection get: description: | List your notifications. List all notifications for the current user, grouped by repository. queryParameters: all: description: True to show notifications marked as read. type: string participating: description: | True to show only notifications in which the user is directly participating or mentioned. type: string since: description: | Time filters out any notifications updated before the given time. The time should be passed in as UTC in the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Example: "2012-10-09T23:39:01Z". type: string responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "id": { "type": "integer" }, "repository": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" } }, "type": "object" }, "subject": { "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "latest_comment_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "reason": { "type": "string" }, "unread": { "type": "boolean" }, "updated_at": { "type": "string" }, "last_read_at": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1, "repository": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World" }, "subject": { "title": "Greetings", "url": "https://api.github.com/repos/pengwynn/octokit/issues/123", "latest_comment_url": "https://api.github.com/repos/pengwynn/octokit/issues/comments/123", "type": "Issue" }, "reason": "subscribed", "unread": true, "updated_at": "2012-09-25T07:54:41-07:00", "last_read_at": "2012-09-25T07:54:41-07:00", "url": "https://api.github.com/notifications/threads/1" } ] put: description: | Mark as read. Marking a notification as "read" removes it from the default view on GitHub.com. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "last_read_at": { "description": "Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now.", "type": "string" } } } responses: 205: description: Marked as read. /threads/{id}: uriParameters: id: description: Id of a thread. type: integer type: item get: description: View a single thread. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "id": { "type": "integer" }, "repository": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" } }, "type": "object" }, "subject": { "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "latest_comment_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "reason": { "type": "string" }, "unread": { "type": "boolean" }, "updated_at": { "type": "string" }, "last_read_at": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1, "repository": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World" }, "subject": { "title": "Greetings", "url": "https://api.github.com/repos/pengwynn/octokit/issues/123", "latest_comment_url": "https://api.github.com/repos/pengwynn/octokit/issues/comments/123", "type": "Issue" }, "reason": "subscribed", "unread": true, "updated_at": "2012-09-25T07:54:41-07:00", "last_read_at": "2012-09-25T07:54:41-07:00", "url": "https://api.github.com/notifications/threads/1" } ] patch: responses: 205: description: Thread marked as read. /subscription: type: item get: description: Get a Thread Subscription. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "subscribed":{ "type": "boolean" }, "ignored": { "type": "boolean" }, "reason": { "type": "boolean" }, "created_at": { "type": "string" }, "url": { "type": "string" }, "thread_url": { "type": "string" } } } example: | { "subscribed": true, "ignored": false, "reason": null, "created_at": "2012-10-06T21:34:12Z", "url": "https://api.github.com/notifications/threads/1/subscription", "thread_url": "https://api.github.com/notifications/threads/1" } put: description: | Set a Thread Subscription. This lets you subscribe to a thread, or ignore it. Subscribing to a thread is unnecessary if the user is already subscribed to the repository. Ignoring a thread will mute all future notifications (until you comment or get @mentioned). body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "subscribed": { "description": "Determines if notifications should be received from this thread.", "type": "boolean" }, "ignored": { "description": "Determines if all notifications should be blocked from this thread.", "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "subscribed":{ "type": "boolean" }, "ignored": { "type": "boolean" }, "reason": { "type": "boolean" }, "created_at": { "type": "string" }, "url": { "type": "string" }, "thread_url": { "type": "string" } } } example: | { "subscribed": true, "ignored": false, "reason": null, "created_at": "2012-10-06T21:34:12Z", "url": "https://api.github.com/notifications/threads/1/subscription", "thread_url": "https://api.github.com/notifications/threads/1" } delete: description: Delete a Thread Subscription. /gists: securedBy: [ null, oauth_2_0 ] type: collection get: is: [ historical ] description: | List the authenticated user's gists or if called anonymously, this will return all public gists. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "gists": [ { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "type": "string" } } } ] } example: | [ { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z" } ] post: description: Create a gist. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "description": { "type": "string" }, "public": { "type": "boolean" }, "files": { "description": "Files that make up this gist. The key of which should be a required string filename and the value another required hash with parameter 'content'.", "type": "string" }, "content": { "description": "File contents.", "type": "string" } }, "required": [ "public", "files", "content" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" }, "forks": [ { "properties": { "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "url": { "type": "string" }, "created_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" } }, "type": "object" } ], "type": "array", "history": [ { "properties": { "url": { "type": "string" }, "version": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "change_status": { "properties": { "deletions": { "type": "integer" }, "additions": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "committed_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" }, "type": "object" } } ] } } example: | { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z", "forks": [ { "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "url": "https://api.github.com/gists/d39d0d37fb24f12e2045", "created_at": "2011-04-14T16:00:49Z" } ], "history": [ { "url": "https://api.github.com/gists/3a8bdc16d2e39d809469", "version": "57a7f021a713b1c5a6a199b54cc514735d2d462f", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "change_status": { "deletions": 0, "additions": 180, "total": 180 }, "committed_at": "2010-04-14T02:15:15Z" } ] } # Public /public: securedBy: [ null, oauth_2_0 ] type: collection get: is: [ historical ] description: List all public gists. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "gists": [ { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "type": "string" } } } ] } example: | [ { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z" } ] # Starred /starred: securedBy: [ null, oauth_2_0 ] type: collection get: is: [ historical ] description: List the authenticated user's starred gists. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "gists": [ { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "type": "string" } } } ] } example: | [ { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z" } ] # ID /{id}: uriParameters: id: description: Id of a thread. type: integer type: item get: description: Get a single gist. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" }, "forks": [ { "properties": { "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "url": { "type": "string" }, "created_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" } }, "type": "object" } ], "type": "array", "history": [ { "properties": { "url": { "type": "string" }, "version": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "change_status": { "properties": { "deletions": { "type": "integer" }, "additions": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "committed_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" }, "type": "object" } } ] } } example: | { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z", "forks": [ { "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "url": "https://api.github.com/gists/d39d0d37fb24f12e2045", "created_at": "2011-04-14T16:00:49Z" } ], "history": [ { "url": "https://api.github.com/gists/3a8bdc16d2e39d809469", "version": "57a7f021a713b1c5a6a199b54cc514735d2d462f", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "change_status": { "deletions": 0, "additions": 180, "total": 180 }, "committed_at": "2010-04-14T02:15:15Z" } ] } patch: description: Edit a gist. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "description": { "type": "string" }, "files": { "properties": { "file1.txt": { "properties": { "content": { "type": "string" } }, "type": "object" }, "old_name.txt": { "properties": { "filename": { "type": "string" }, "content": { "type": "string" } }, "type": "object" }, "new_file.txt": { "properties": { "content": { "type": "string" } }, "type": "object" }, "delete_this_file.txt": { "type": "string" } } } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" }, "forks": [ { "properties": { "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "url": { "type": "string" }, "created_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" } }, "type": "object" } ], "type": "array", "history": [ { "properties": { "url": { "type": "string" }, "version": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "change_status": { "properties": { "deletions": { "type": "integer" }, "additions": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "committed_at": { "description": "Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "type": "string" }, "type": "object" } } ] } } example: | { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z", "forks": [ { "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "url": "https://api.github.com/gists/d39d0d37fb24f12e2045", "created_at": "2011-04-14T16:00:49Z" } ], "history": [ { "url": "https://api.github.com/gists/3a8bdc16d2e39d809469", "version": "57a7f021a713b1c5a6a199b54cc514735d2d462f", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "change_status": { "deletions": 0, "additions": 180, "total": 180 }, "committed_at": "2010-04-14T02:15:15Z" } ] } delete: description: Delete a gist. # Star /star: type: base put: description: Star a gist. responses: 204: description: Starred. delete: description: Unstar a gist. responses: 204: description: Item removed. get: description: Check if a gist is starred. responses: 204: description: Exists. 404: description: Not exists. # Forks /forks: type: base post: description: Fork a gist. responses: 204: description: Exists. 404: description: Not exists. /comments: type: collection get: description: List comments on a gist. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "comments": [ { "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601.", "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1, "url": "https://api.github.com/gists/ae709e9cf889e485e65f/comments/1", "body": "Just commenting for the sake of commenting", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-18T23:23:56Z" } ] post: description: Create a comment body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601.", "type": "string" } } } example: | { "id": 1, "url": "https://api.github.com/gists/83ba86d111d39709da8c/comments/1", "body": "Just commenting for the sake of commenting", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-18T23:23:56Z" } /{commentId}: type: item uriParameters: commentId: description: Id of the comment. type: integer get: description: Get a single comment. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601.", "type": "string" } } } example: | { "id": 1, "url": "https://api.github.com/gists/83ba86d111d39709da8c/comments/1", "body": "Just commenting for the sake of commenting", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-18T23:23:56Z" } patch: description: Edit a comment. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601.", "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601.", "type": "string" } } } example: | { "id": 1, "url": "https://api.github.com/gists/83ba86d111d39709da8c/comments/1", "body": "Just commenting for the sake of commenting", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-18T23:23:56Z" } delete: description: Delete a comment. /orgs/{orgId}: uriParameters: orgId: description: Id of organisation. type: integer type: item get: description: Get an Organization. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "avatar_url": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "blog": { "type": "string" }, "location": { "type": "string" }, "email": { "type": "string" }, "public_repos": { "type": "integer" }, "public_gists": { "type": "integer" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "html_url": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "type": { "type": "string" } } } example: | { "login": "github", "id": 1, "url": "https://api.github.com/orgs/github", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "name": "github", "company": "GitHub", "blog": "https://github.com/blog", "location": "San Francisco", "email": "octocat@github.com", "public_repos": 2, "public_gists": 1, "followers": 20, "following": 0, "html_url": "https://github.com/octocat", "created_at": "2008-01-14T04:33:35Z", "type": "Organization" } patch: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "billing_email": { "description": "Billing email address. This address is not publicized.", "type": "string" }, "company": { "type": "string" }, "email": { "description": "Publicly visible email address.", "type": "string" }, "location": { "type": "string" }, "name": { "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "avatar_url": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "blog": { "type": "string" }, "location": { "type": "string" }, "email": { "type": "string" }, "public_repos": { "type": "integer" }, "public_gists": { "type": "integer" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "html_url": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "type": { "type": "string" } } } example: | { "login": "github", "id": 1, "url": "https://api.github.com/orgs/github", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "name": "github", "company": "GitHub", "blog": "https://github.com/blog", "location": "San Francisco", "email": "octocat@github.com", "public_repos": 2, "public_gists": 1, "followers": 20, "following": 0, "html_url": "https://github.com/octocat", "created_at": "2008-01-14T04:33:35Z", "type": "Organization" } description: Edit an Organization. # Events /events: type: collection get: description: List public events for an organization. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] # Issues /issues: type: collection get: is: [ filterable ] description: | List issues. List all issues for a given organization for the authenticated user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "issues": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } ] /members: type: collection get: description: | Members list. List all users who are members of an organization. A member is a user that belongs to at least 1 team in the organization. If the authenticated user is also an owner of this organization then both concealed and public members will be returned. If the requester is not an owner of the organization the query will be redirected to the public members list. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] 302: description: Response if requester is not an organization member. /{userId}: type: item uriParameters: userId: description: Id of the user. type: integer delete: description: | Remove a member. Removing a user from this list will remove them from all teams and they will no longer have any access to the organization's repositories. /public_members: type: collection get: description: | Public members list. Members of an organization can choose to have their membership publicized or not. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] /{userId}: uriParameters: userId: description: Id of the user. type: integer type: base get: description: Check public membership. responses: 204: description: User is a public member. 404: description: User is not a public member. put: description: Publicize a user's membership. responses: 204: description: Publicized. delete: description: Conceal a user's membership. responses: 204: description: Concealed. /teams: type: collection get: description: List teams. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/teams/1", "name": "Owners", "id": 1 } ] post: description: | Create team. In order to create a team, the authenticated user must be an owner of orgId. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "repo_names": [ { "type": "string" } ], "type": "array", "permission": { "enum": [ "pull", "push", "admin" ] } }, "required": [ "name" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "integer" }, "permission": { "type": "string" }, "members_count": { "type": "integer" }, "repos_count": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/teams/1", "name": "Owners", "id": 1 } ] /repos: type: collection get: description: List repositories for the specified org. queryParameters: type: enum: - all - public - private - forks - sources - member default: all responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] post: description: | Create a new repository for the authenticated user. OAuth users must supply repo scope. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "homepage": { "type": "string" }, "private": { "description": "True to create a private repository, false to create a public one. Creating private repositories requires a paid GitHub account.", "type": "boolean" }, "has_issues": { "description": "True to enable issues for this repository, false to disable them. Default is true.", "type": "boolean" }, "has_wiki": { "description": "True to enable the wiki for this repository, false to disable it. Default is true.", "type": "boolean" }, "has_downloads": { "description": "True to enable downloads for this repository, false to disable them. Default is true.", "type": "boolean" }, "team_id": { "description": "The id of the team that will be granted access to this repository. This is only valid when creating a repo in an organization.", "type": "integer" }, "auto_init": { "description": "True to create an initial commit with empty README. Default is false.", "type": "boolean" }, "gitignore_template": { "description": "Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, \"Haskell\" Ignored if auto_init parameter is not provided. ", "type": "string" } }, "required": [ "name" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /teams/{teamsId}: uriParameters: teamsId: description: Id of a team. type: integer type: item get: description: Get team. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "integer" }, "permission": { "type": "string" }, "members_count": { "type": "integer" }, "repos_count": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/teams/1", "name": "Owners", "id": 1 } ] patch: description: | Edit team. In order to edit a team, the authenticated user must be an owner of the org that the team is associated with. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "permission": { "values": [ "pull", "push", "admin" ] } }, "required": [ "name" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "integer" }, "permission": { "type": "string" }, "members_count": { "type": "integer" }, "repos_count": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/teams/1", "name": "Owners", "id": 1 } ] delete: description: | Delete team. In order to delete a team, the authenticated user must be an owner of the org that the team is associated with. /members: type: collection get: description: | List team members. In order to list members in a team, the authenticated user must be a member of the team. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] /{userId}: uriParameters: userId: description: Id of a member. type: integer type: base get: description: | Get team member. In order to get if a user is a member of a team, the authenticated user must be a member of the team. responses: 204: description: User is a member. 404: description: User is not a member. put: description: | Add team member. In order to add a user to a team, the authenticated user must have 'admin' permissions to the team or be an owner of the org that the team is associated with. responses: 204: description: Team member added. 422: description: If you attempt to add an organization to a team, you will get this. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "message": { "type": "string" }, "errors": [ { "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "resource": { "type": "string" } }, "type": "object" } ], "type": "object" } } example: | { "message": "Validation Failed", "errors": [ { "code": "org", "field": "user", "resource": "TeamMember" } ] } delete: description: | Remove team member. In order to remove a user from a team, the authenticated user must have 'admin' permissions to the team or be an owner of the org that the team is associated with. NOTE This does not delete the user, it just remove them from the team. responses: 204: description: Team member removed. /repositories: type: collection get: securedBy: [ null, oauth_2_0 ] description: | List all public repositories. This provides a dump of every public repository, in the order that they were created. Note: Pagination is powered exclusively by the since parameter. is the Link header to get the URL for the next page of repositories. queryParameters: since: description: | The integer ID of the last Repository that you've seen. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World" } ] /repos/{ownerId}/{repoId}: uriParameters: ownerId: description: Id of the owner. type: integer repoId: description: Id of repository. type: integer type: item get: description: Get repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "organization": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "parent": { "description": "Is present when the repo is a fork. Parent is the repo this repo was forked from.", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "source": { "description": "Is present when the repo is a fork. Source is the ultimate source for the network.", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "has_issues": { "type": "boolean" }, "has_wiki": { "type": "boolean" }, "has_downloads": { "type": "boolean" } } } example: | { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z", "organization": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "type": "Organization" }, "parent": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" }, "source": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" }, "has_issues": true, "has_wiki": true, "has_downloads": true } patch: description: Edit repository. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "homepage": { "type": "string" }, "private": { "description": "True makes the repository private, and false makes it public.", "type": "boolean" }, "has_issues": { "description": "True to enable issues for this repository, false to disable them. Default is true.", "type": "boolean" }, "has_wiki": { "description": "True to enable the wiki for this repository, false to disable it. Default is true.", "type": "boolean" }, "has_downloads": { "description": "True to enable downloads for this repository, false to disable them. Default is true.", "type": "boolean" }, "default_branch": { "description": "Update the default branch for this repository.", "type": "string" } }, "required": [ "name" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "organization": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "parent": { "description": "Is present when the repo is a fork. Parent is the repo this repo was forked from.", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "source": { "description": "Is present when the repo is a fork. Source is the ultimate source for the network.", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "has_issues": { "type": "boolean" }, "has_wiki": { "type": "boolean" }, "has_downloads": { "type": "boolean" } } } example: | { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z", "organization": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "type": "Organization" }, "parent": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" }, "source": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" }, "has_issues": true, "has_wiki": true, "has_downloads": true } delete: description: | Delete a Repository. Deleting a repository requires admin access. If OAuth is used, the delete_repo scope is required. # Events /events: type: collection get: description: Get list of repository events. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] # Languages /languages: type: collection get: description: | List languages. List languages for the specified repository. The value on the right of a language is the number of bytes of code written in that language. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "language": { "type": "string" }, "count": { "type": "string" } } } example: | { "C": 78769, "Python": 7769 } # GIT /git: /blobs: type: collection post: description: Create a Blob. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "content": { "type": "string" }, "encoding": { "enum": [ "utf-8", "base64" ] }, "sha": { "type": "string" }, "size": { "type": "integer" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" } } } example: | { "sha": "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15" } /{shaCode}: uriParameters: shaCode: description: SHA-1 code. type: string type: item get: description: | Get a Blob. Since blobs can be any arbitrary binary data, the input and responses for the blob API takes an encoding parameter that can be either utf-8 or base64. If your data cannot be losslessly sent as a UTF-8 string, you can base64 encode it. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "content": { "type": "string" }, "encoding": { "enum": [ "utf-8", "base64" ] }, "sha": { "type": "string" }, "size": { "type": "integer" } } } example: | { "content": "Content of the blob", "encoding": "utf-8", "sha": "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15", "size": 100 } /commits: type: item post: description: Create a Commit. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "message": { "description": "String of the commit message", "type": "string" }, "tree": { "description": "String of the SHA of the tree object this commit points to.", "type": "string" }, "parents": [ { "description": "Array of the SHAs of the commits that were the parents of this commit. If omitted or empty, the commit will be written as a root commit. For a single parent, an array of one SHA should be provided, for a merge commit, an array of more than one should be provided.", "type": "string" } ], "type": "array", "author": { "properties": { "name": { "description": "String of the name of the author of the commit.", "type": "string" }, "email": { "description": "String of the email of the author of the commit.", "type": "string" }, "date": { "description": "Timestamp of when this commit was authored.", "type": "timestamp" } }, "type": "object" }, "committer": { "properties": { "name": { "description": "String of the name of the committer of the commit.", "type": "string" }, "email": { "description": "String of the email of the committer of the commit.", "type": "string" }, "date": { "description": "Timestamp of when this commit was committed.", "type": "timestamp" } }, "type": "object" } }, "required": [ "message", "tree", "parents" ] } responses: 201: body: schema: | { "": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "message": { "type": "string" }, "author": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "type": "string" } }, "type": "object" }, "parents": [ { "type": "string" } ], "tree": { "type": "string" } } } example: | { "message": "my commit message", "author": { "name": "Scott Chacon", "email": "schacon@gmail.com", "date": "2008-07-09T16:13:30 12:00" }, "parents": [ "7d1b31e74ee336d15cbd21741bc88a537ed063a0" ], "tree": "827efc6d56897b048c772eb4087f854f46256132" } /{shaCode}: uriParameters: shaCode: description: SHA-1 code. type: string type: item get: description: Get a Commit. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" }, "url": { "type": "string" }, "author": { "properties": { "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "tree": { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } ], "type": "array" } } example: | { "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2010-04-10T14:10:01-07:00", "name": "Scott Chacon", "email": "schacon@gmail.com" }, "committer": { "date": "2010-04-10T14:10:01-07:00", "name": "Scott Chacon", "email": "schacon@gmail.com" }, "message": "added readme, because im a good github citizen\n", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb", "sha": "691272480426f78a0138979dd3ce63b77f706feb" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5", "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5" } ] } /refs: type: collection get: description: Get all References responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "references": [ { "properties": { "ref": { "type": "string" }, "url": { "type": "string" }, "object": { "properties": { "type": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "ref": "refs/heads/master", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/master", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } }, { "ref": "refs/heads/gh-pages", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/gh-pages", "object": { "type": "commit", "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac" } }, { "ref": "refs/tags/v0.0.1", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/tags/v0.0.1", "object": { "type": "tag", "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac", "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac" } } ] post: description: Create a Reference body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "ref": { "description": "String of the name of the fully qualified reference (ie: refs/heads/master). If it doesn't start with ?refs' and have at least two slashes, it will be rejected.", "type": "string" }, "sha": { "description": "String of the SHA1 value to set this reference to.", "type": "string" } }, "required": [ "ref", "sha" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "ref": { "type": "string" }, "url": { "type": "string" }, "object": { "properties": { "type": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } } example: | { "ref": "refs/heads/sc/featureA", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/sc/featureA", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } } /{heads}: uriParameters: heads: description: Subfolder of path to the branch. type: string type: collection get: description: Get list of subdirectories. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "name": { "type": "string" }, "commit": { "properties": { "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "zipball_url": { "type": "string" }, "tarball_url": { "type": "string" } }, "type": "object" } ] } example: | [ { "name": "v0.1", "commit": { "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc", "url": "https://api.github.com/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc" }, "zipball_url": "https://github.com/octocat/Hello-World/zipball/v0.1", "tarball_url": "https://github.com/octocat/Hello-World/tarball/v0.1" } ] /{branch}: type: item uriParameters: branch: description: Path to the branch. type: string get: description: Get a Reference. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "ref": { "type": "string" }, "url": { "type": "string" }, "object": { "properties": { "type": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } } example: | { "ref": "refs/heads/sc/featureA", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/sc/featureA", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } } patch: description: Update a Reference body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "description": "String of the SHA1 value to set this reference to.", "type": "string" }, "force": { "description": "Boolean indicating whether to force the update or to make sure the update is a fast-forward update. The default is false, so leaving this out or setting it to false will make sure you're not overwriting work.", "type": "boolean" } }, "required": [ "sha", "force" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "ref": { "type": "string" }, "url": { "type": "string" }, "object": { "properties": { "type": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } } example: | { "ref": "refs/heads/sc/featureA", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/sc/featureA", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } } delete: description: Delete a Reference. /tags: type: collection post: description: | Create a Tag Object. Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then create the refs/tags/[tag] reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "tag": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" }, "message": { "type": "string" }, "tagger": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "object": { "properties": { "type": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "tag": { "type": "string" }, "message": { "description": "String of the tag message.", "type": "string" }, "object": { "description": "String of the SHA of the git object this is tagging.", "type": "string" }, "type": { "description": "String of the type of the object we're tagging. Normally this is a commit but it can also be a tree or a blob.", "type": "string" }, "tagger": { "properties": { "name": { "description": "String of the name of the author of the tag.", "type": "string" }, "email": { "description": "String of the email of the author of the tag.", "type": "string" }, "date": { "description": "Timestamp of when this object was tagged.", "type": "timestamp" } }, "type": "object" } }, "required": [ "tag", "message", "object", "type", "tagger" ] } example: | { "tag": "v0.0.1", "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac", "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac", "message": "initial version\n", "tagger": { "name": "Scott Chacon", "email": "schacon@gmail.com", "date": "2011-06-17T14:53:35-07:00" }, "object": { "type": "commit", "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c" } } /{shaCode}: type: item get: description: Get a Tag. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "tag": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" }, "message": { "type": "string" }, "tagger": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "object": { "properties": { "type": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } } example: | { "tag": "v0.0.1", "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac", "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac", "message": "initial version\n", "tagger": { "name": "Scott Chacon", "email": "schacon@gmail.com", "date": "2011-06-17T14:53:35-07:00" }, "object": { "type": "commit", "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c" } } /trees: type: collection post: description: | Create a Tree. The tree creation API will take nested entries as well. If both a tree and a nested path modifying that tree are specified, it will overwrite the contents of that tree with the new path contents and write a new tree out. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" }, "url": { "type": "string" }, "tree": [ { "path": { "type": "string" }, "mode": { "type": "string" }, "type": { "type": "string" }, "size": { "type": "integer" }, "sha": { "type": "string" }, "url": { "type": "string" } } ], "type": "array" } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "base_tree": { "type": "string" }, "tree": [ { "properties": { "path": { "type": "string" }, "mode": { "description": "One of 100644 for file (blob), 100755 for executable (blob), 040000 for subdirectory (tree), 160000 for submodule (commit) or 120000 for a blob that specifies the path of a symlink.", "type": "string", "enum": [ "100644", "100755", "040000", "160000", "120000" ] }, "type": { "type": "string", "enum": [ "blob", "tree", "commit" ] }, "oneOf": [ { "sha": { "description": "SHA1 checksum ID of the object in the tree.", "type": "string" } }, { "content": { "description": "content you want this file to have - GitHub will write this blob out and use that SHA for this entry.", "type": "string" } } ] }, "type": "object" } ], "type": "array" }, "required": [ "tree" ] } example: | { "sha": "cd8274d15fa3ae2ab983129fb037999f264ba9a7", "url": "https://api.github.com/repo/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7", "tree": [ { "path": "file.rb", "mode": "100644", "type": "blob", "size": 132, "sha": "7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b", "url": "https://api.github.com/octocat/Hello-World/git/blobs/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b" } ] } /{shaCode}: uriParameters: shaCode: description: Id of the owner. type: integer type: item get: description: Get a Tree. queryParameters: recursive: description: Get a Tree Recursively. (0 or 1) type: integer responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" }, "url": { "type": "string" }, "tree": [ { "path": { "type": "string" }, "mode": { "type": "string" }, "type": { "type": "string" }, "size": { "type": "integer" }, "sha": { "type": "string" }, "url": { "type": "string" } } ], "type": "array" } } example: | { "sha": "9fb037999f264ba9a7fc6274d15fa3ae2ab98312", "url": "https://api.github.com/repos/octocat/Hello-World/trees/9fb037999f264ba9a7fc6274d15fa3ae2ab98312", "tree": [ { "path": "file.rb", "mode": "100644", "type": "blob", "size": 30, "sha": "44b4fc6d56897b048c772eb4087f854f46256132", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132" }, { "path": "subdir", "mode": "040000", "type": "tree", "sha": "f484d249c660418515fb01c2b9662073663c242e", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/f484d249c660418515fb01c2b9662073663c242e" }, { "path": "exec_file", "mode": "100755", "type": "blob", "size": 75, "sha": "45b983be36b73c0788dc9cbcb76cbb80fc7bb057", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/45b983be36b73c0788dc9cbcb76cbb80fc7bb057" } ] } # Readme /readme: type: item get: description: | Get the README. This method returns the preferred README for a repository. queryParameters: ref: description: The String name of the Commit/Branch/Tag. Defaults to master. type: string responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "type": "string" }, "encoding": { "type": "string" }, "size": { "type": "integer" }, "name": { "type": "string" }, "path": { "type": "string" }, "content": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" }, "git_url": { "type": "string" }, "html_url": { "type": "string" }, "_links": { "properties": { "git": { "type": "string" }, "self": { "type": "string" }, "html": { "type": "string" } }, "type": "object" } } } example: | { "type": "file", "encoding": "base64", "size": 5362, "name": "README.md", "path": "README.md", "content": "encoded content ...", "sha": "3d21ec53a331a6f037a91c368710b99387d012c1", "url": "https://api.github.com/repos/pengwynn/octokit/contents/README.md", "git_url": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1", "html_url": "https://github.com/pengwynn/octokit/blob/master/README.md", "_links": { "git": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1", "self": "https://api.github.com/repos/pengwynn/octokit/contents/README.md", "html": "https://github.com/pengwynn/octokit/blob/master/README.md" } } # Stargazers /stargazers: type: collection get: description: List Stargazers. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] # Subscribers /subscribers: type: collection get: description: List watchers. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] # Tags /tags: type: collection get: description: Get list of tags. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "tag": { "type": "string" }, "message": { "description": "String of the tag message.", "type": "string" }, "object": { "description": "String of the SHA of the git object this is tagging.", "type": "string" }, "type": { "description": "String of the type of the object we're tagging. Normally this is a commit but it can also be a tree or a blob.", "type": "string" }, "tagger": { "properties": { "name": { "description": "String of the name of the author of the tag.", "type": "string" }, "email": { "description": "String of the email of the author of the tag.", "type": "string" }, "date": { "description": "Timestamp of when this object was tagged.", "type": "timestamp" } }, "type": "object" } }, "required": [ "tag", "message", "object", "type", "tagger" ] } example: | { "tag": "v0.0.1", "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac", "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac", "message": "initial version\n", "tagger": { "name": "Scott Chacon", "email": "schacon@gmail.com", "date": "2011-06-17T14:53:35-07:00" }, "object": { "type": "commit", "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c" } } # Teams /teams: type: collection get: description: Get list of teams responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/teams/1", "name": "Owners", "id": 1 } ] # Watchers /watchers: type: collection get: description: List Stargazers. New implementation. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] # Other links /contributors: type: collection get: description: Get list of contributors. queryParameters: anon: description: Set to 1 or true to include anonymous contributors in results. type: string required: true responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "contributions": { "type": "integer" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "contributions": 32 } ] /branches: type: collection get: description: Get list of branches responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "name": { "type": "string" }, "commit": { "properties": { "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "name": "master", "commit": { "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc" } } ] /{branchId}: uriParameters: branchId: description: Id of the branch. type: integer type: item get: description: Get Branch responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "commit": { "properties": { "sha": { "type": "string" }, "commit": { "author": { "name": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "email": { "type": "string" } }, "url": { "type": "string" }, "message": { "type": "string" }, "tree": { "properties": { "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "name": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "email": { "type": "string" } }, "type": "object" } }, "type": "object" }, "author": { "properties": { "gravatar_id": { "type": "string" }, "avatar_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "login": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ], "type": "array", "url": { "type": "string" }, "committer": { "properties": { "gravatar_id": { "type": "string" }, "avatar_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "login": { "type": "string" } }, "type": "object" } }, "_links": { "properties": { "html": { "type": "string" }, "self": { "type": "string" } }, "type": "object" } } } example: | { "name": "master", "commit": { "sha": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "commit": { "author": { "name": "The Octocat", "date": "2012-03-06T15:06:50-08:00", "email": "octocat@nowhere.com" }, "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "message": "Merge pull request #6 from Spaceghost/patch-1\n\nNew line at end of file.", "tree": { "sha": "b4eecafa9be2f2006ce1b709d6857b07069b4608", "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/b4eecafa9be2f2006ce1b709d6857b07069b4608" }, "committer": { "name": "The Octocat", "date": "2012-03-06T15:06:50-08:00", "email": "octocat@nowhere.com" } }, "author": { "gravatar_id": "7ad39074b0584bc555d0417ae3e7d974", "avatar_url": "https://secure.gravatar.com/avatar/7ad39074b0584bc555d0417ae3e7d974?d=https://a248.e.akamai.net/assets.github.com/images/gravatars/gravatar-140.png", "url": "https://api.github.com/users/octocat", "id": 583231, "login": "octocat" }, "parents": [ { "sha": "553c2077f0edc3d5dc5d17262f6aa498e69d6f8e", "url": "https://api.github.com/repos/octocat/Hello-World/commits/553c2077f0edc3d5dc5d17262f6aa498e69d6f8e" }, { "sha": "762941318ee16e59dabbacb1b4049eec22f0d303", "url": "https://api.github.com/repos/octocat/Hello-World/commits/762941318ee16e59dabbacb1b4049eec22f0d303" } ], "url": "https://api.github.com/repos/octocat/Hello-World/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "committer": { "gravatar_id": "7ad39074b0584bc555d0417ae3e7d974", "avatar_url": "https://secure.gravatar.com/avatar/7ad39074b0584bc555d0417ae3e7d974?d=https://a248.e.akamai.net/assets.github.com/images/gravatars/gravatar-140.png", "url": "https://api.github.com/users/octocat", "id": 583231, "login": "octocat" } }, "_links": { "html": "https://github.com/octocat/Hello-World/tree/master", "self": "https://api.github.com/repos/octocat/Hello-World/branches/master" } } /issues: type: collection get: is: [ filterable ] description: List issues for a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "issues": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } ] post: description: | Create an issue. Any user with pull access to a repository can create an issue. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "assignee": { "description": "Login for the user that this issue should be assigned to. NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise.", "type": "string" }, "milestone": { "description": "Milestone to associate this issue with. NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise.", "type": "integer" }, "labels": [ { "description": "Array of strings - Labels to associate with this issue. NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise.", "type": "string" } ], "type": "array" }, "required": [ "title" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } /events: type: collection get: description: List issue events for a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] /{eventId}: uriParameters: eventId: description: Id of the event. type: integer type: item get: description: Get a single event. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "type": "object" }, "event": { "type": "string" }, "commit_id": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "issue": { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/issues/events/1", "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "event": "closed", "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "created_at": "2011-04-14T16:00:49Z", "issue": { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } } /{number}: uriParameters: number: description: Id of the issue. type: integer type: item get: description: Get a single issue responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } patch: description: | Edit an issue. Issue owners and users with push access can edit an issue. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } # Comments /comments: type: collection get: description: List comments on an issue. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } ] post: description: Create a comment. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "id": 1, "url": "https://api.github.com/repos/octocat/Hello-World/issues/comments/1", "html_url": "https://github.com/octocat/Hello-World/issues/1347#issuecomment-1", "body": "Me too", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } # Events /events: type: collection get: description: List issue events for a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] /{eventId}: uriParameters: eventId: description: Id of the event. type: integer type: item get: description: Get a single event. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "type": "object" }, "event": { "type": "string" }, "commit_id": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "issue": { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/issues/events/1", "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "event": "closed", "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "created_at": "2011-04-14T16:00:49Z", "issue": { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } } # Labels /labels: type: collection get: description: List labels on an issue. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ] post: description: Add labels to an issue. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "color": { "description": "6 character hex code, without a leading #.", "type": "string", "minLength": 6, "maxLength": 6 } }, "required": [ "name", "color" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } put: description: | Replace all labels for an issue. Sending an empty array ([]) will remove all Labels from the Issue. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "color": { "description": "6 character hex code, without a leading #.", "type": "string", "minLength": 6, "maxLength": 6 } }, "required": [ "name", "color" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } delete: description: Remove all labels from an issue. /{name}: uriParameters: name: description: Name of the label. type: string type: base delete: description: Remove a label from an issue. responses: 204: description: Item removed. /comments: type: collection get: description: List comments in a repository. queryParameters: sort: enum: - created - updated direction: description: Ignored without sort parameter. enum: - asc - desc since: description: Timestamp in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. type: string responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } ] /{commentId}: uriParameters: commentId: description: Id of the comment. type: integer type: item get: description: Get a single comment. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "id": 1, "url": "https://api.github.com/repos/octocat/Hello-World/issues/comments/1", "html_url": "https://github.com/octocat/Hello-World/issues/1347#issuecomment-1", "body": "Me too", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } patch: description: Edit a comment. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "id": 1, "url": "https://api.github.com/repos/octocat/Hello-World/issues/comments/1", "html_url": "https://github.com/octocat/Hello-World/issues/1347#issuecomment-1", "body": "Me too", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } delete: description: Delete a comment. /notifications: type: collection get: description: | List your notifications in a repository List all notifications for the current user. queryParameters: all: description: True to show notifications marked as read. type: string participating: description: | True to show only notifications in which the user is directly participating or mentioned. type: string since: description: | Time filters out any notifications updated before the given time. The time should be passed in as UTC in the ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. Example: "2012-10-09T23:39:01Z". type: string responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "id": { "type": "integer" }, "repository": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" } }, "type": "object" }, "subject": { "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "latest_comment_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "reason": { "type": "string" }, "unread": { "type": "boolean" }, "updated_at": { "type": "string" }, "last_read_at": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1, "repository": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World" }, "subject": { "title": "Greetings", "url": "https://api.github.com/repos/pengwynn/octokit/issues/123", "latest_comment_url": "https://api.github.com/repos/pengwynn/octokit/issues/comments/123", "type": "Issue" }, "reason": "subscribed", "unread": true, "updated_at": "2012-09-25T07:54:41-07:00", "last_read_at": "2012-09-25T07:54:41-07:00", "url": "https://api.github.com/notifications/threads/1" } ] put: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "last_read_at": { "description": "Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now.", "type": "string" } } } description: | Mark notifications as read in a repository. Marking all notifications in a repository as "read" removes them from the default view on GitHub.com. responses: 205: description: Marked as read. /subscription: type: collection get: description: Get a Repository Subscription. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "subscribed": { "type": "boolean" }, "ignored": { "type": "boolean" }, "reason": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "url": { "type": "string" }, "repository_url": { "type": "string" } } } example: | { "subscribed": true, "ignored": false, "reason": null, "created_at": "2012-10-06T21:34:12Z", "url": "https://api.github.com/repos/octocat/example/subscription", "repository_url": "https://api.github.com/repos/octocat/example" } put: description: Set a Repository Subscription body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "subscribed": { "description": "Determines if notifications should be received from this repository.", "type": "boolean" }, "ignored": { "description": "Determines if all notifications should be blocked from this repository.", "type": "boolean" } }, "required": [ "subscribed", "ignored" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "subscribed": { "type": "boolean" }, "ignored": { "type": "boolean" }, "reason": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "url": { "type": "string" }, "repository_url": { "type": "string" } } } example: | { "subscribed": true, "ignored": false, "reason": null, "created_at": "2012-10-06T21:34:12Z", "url": "https://api.github.com/repos/octocat/example/subscription", "repository_url": "https://api.github.com/repos/octocat/example" } delete: description: Delete a Repository Subscription. /assignees: type: collection get: description: | List assignees. This call lists all the available assignees (owner collaborators) to which issues may be assigned. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "integer" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] /{assignee}: type: base uriParameters: assignee: description: Login of the assignee. type: string get: description: | Check assignee. You may also check to see if a particular user is an assignee for a repository. responses: 204: description: User is an assignee. 404: description: User isn't an assignee. /labels: type: collection get: description: List all labels for this repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ] post: description: Create a label. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "color": { "description": "6 character hex code, without a leading #.", "type": "string", "minLength": 6, "maxLength": 6 } }, "required": [ "name", "color" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } /{name}: uriParameters: name: description: Name of the label. type: string type: item get: description: Get a single label. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } patch: description: Update a label. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "color": { "description": "6 character hex code, without a leading #.", "type": "string", "minLength": 6, "maxLength": 6 } }, "required": [ "name", "color" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } delete: description: Delete a label. /milestones: type: collection get: description: List milestones for a repository. queryParameters: state: enum: - open - closed default: open sort: enum: - due_date - completeness default: due_date direction: enum: - asc - desc default: desc responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null } post: description: Create a milestone. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "state": { "enum": [ "open", "closed" ] }, "description": { "type": "string" }, "due_on": { "description": "ISO 8601 time.", "type": "string" } }, "required": [ "title" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null } /{number}: uriParameters: number: description: Id of the milestone. type: integer type: item get: description: Get a single milestone. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null } patch: description: Update a milestone. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "number": { "type": "integer" }, "title": { "type": "string" }, "state": { "enum": [ "open", "closed" ] }, "description": { "type": "string" }, "due_on": { "description": "ISO 8601 time.", "type": "string" } }, "required": [ "number" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null } delete: description: Delete a milestone. /labels: type: collection get: description: Get labels for every issue in a milestone. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "maxLength": 6, "minLength": 6 } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ] /pulls: type: collection get: description: List pull requests. queryParameters: state: description: String to filter by state. enum: - open - closed default: open head: description: | Filter pulls by head user and branch name in the format of 'user:ref-name'. Example: github:new-script-format. type: string base: description: Filter pulls by base branch name. Example - gh-pages. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" }, "issue_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "merged_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "head": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "base": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "comments": { "properties": { "href": { "type": "string" } }, "type": "object" }, "review_comments": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/octocat/Hello-World/pulls/1", "html_url": "https://github.com/octocat/Hello-World/pulls/1", "diff_url": "https://github.com/octocat/Hello-World/pulls/1.diff", "patch_url": "https://github.com/octocat/Hello-World/pulls/1.patch", "issue_url": "https://github.com/octocat/Hello-World/issue/1", "number": 1, "state": "open", "title": "new-feature", "body": "Please pull these awesome changes", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:01:12Z", "closed_at": "2011-01-26T19:01:12Z", "merged_at": "2011-01-26T19:01:12Z", "head": { "label": "new-topic", "ref": "new-topic", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "base": { "label": "master", "ref": "master", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1" }, "comments": { "href": "https://api.github.com/octocat/Hello-World/issues/1/comments" }, "review_comments": { "href": "https://api.github.com/octocat/Hello-World/pulls/1/comments" } }, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } } ] post: description: Create a pull request. responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" }, "issue_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "merged_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "head": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "base": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "comments": { "properties": { "href": { "type": "string" } }, "type": "object" }, "review_comments": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/octocat/Hello-World/pulls/1", "html_url": "https://github.com/octocat/Hello-World/pulls/1", "diff_url": "https://github.com/octocat/Hello-World/pulls/1.diff", "patch_url": "https://github.com/octocat/Hello-World/pulls/1.patch", "issue_url": "https://github.com/octocat/Hello-World/issue/1", "number": 1, "state": "open", "title": "new-feature", "body": "Please pull these awesome changes", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:01:12Z", "closed_at": "2011-01-26T19:01:12Z", "merged_at": "2011-01-26T19:01:12Z", "head": { "label": "new-topic", "ref": "new-topic", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "base": { "label": "master", "ref": "master", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1" }, "comments": { "href": "https://api.github.com/octocat/Hello-World/issues/1/comments" }, "review_comments": { "href": "https://api.github.com/octocat/Hello-World/pulls/1/comments" } }, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } } ] /{number}: uriParameters: number: description: Id of a pull. type: integer type: item get: description: Get a single pull request. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" }, "issue_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "merged_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "head": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "base": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "comments": { "properties": { "href": { "type": "string" } }, "type": "object" }, "review_comments": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } } example: | { "url": "https://api.github.com/octocat/Hello-World/pulls/1", "html_url": "https://github.com/octocat/Hello-World/pulls/1", "diff_url": "https://github.com/octocat/Hello-World/pulls/1.diff", "patch_url": "https://github.com/octocat/Hello-World/pulls/1.patch", "issue_url": "https://github.com/octocat/Hello-World/issue/1", "number": 1, "state": "open", "title": "new-feature", "body": "Please pull these awesome changes", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:01:12Z", "closed_at": "2011-01-26T19:01:12Z", "merged_at": "2011-01-26T19:01:12Z", "head": { "label": "new-topic", "ref": "new-topic", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "base": { "label": "master", "ref": "master", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1" }, "comments": { "href": "https://api.github.com/octocat/Hello-World/issues/1/comments" }, "review_comments": { "href": "https://api.github.com/octocat/Hello-World/pulls/1/comments" } }, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "merge_commit_sha": "e5bd3914e2e596debea16f433f57875b5b90bcd6", "merged": false, "mergeable": true, "merged_by": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "comments": 10, "commits": 3, "additions": 100, "deletions": 3, "changed_files": 5 } patch: description: Update a pull request. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "state": { "enum": [ "open", "closed" ] } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "organization": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "parent": { "description": "Is present when the repo is a fork. Parent is the repo this repo was forked from.", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "source": { "description": "Is present when the repo is a fork. Source is the ultimate source for the network.", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "has_issues": { "type": "boolean" }, "has_wiki": { "type": "boolean" }, "has_downloads": { "type": "boolean" } } } example: | { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z", "organization": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "type": "Organization" }, "parent": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" }, "source": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" }, "has_issues": true, "has_wiki": true, "has_downloads": true } # Files /files: type: item get: description: List pull requests files. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" }, "issue_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "merged_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "head": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "base": { "properties": { "label": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } }, "type": "object" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "comments": { "properties": { "href": { "type": "string" } }, "type": "object" }, "review_comments": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/octocat/Hello-World/pulls/1", "html_url": "https://github.com/octocat/Hello-World/pulls/1", "diff_url": "https://github.com/octocat/Hello-World/pulls/1.diff", "patch_url": "https://github.com/octocat/Hello-World/pulls/1.patch", "issue_url": "https://github.com/octocat/Hello-World/issue/1", "number": 1, "state": "open", "title": "new-feature", "body": "Please pull these awesome changes", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:01:12Z", "closed_at": "2011-01-26T19:01:12Z", "merged_at": "2011-01-26T19:01:12Z", "head": { "label": "new-topic", "ref": "new-topic", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "base": { "label": "master", "ref": "master", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "repo": { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } }, "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1" }, "comments": { "href": "https://api.github.com/octocat/Hello-World/issues/1/comments" }, "review_comments": { "href": "https://api.github.com/octocat/Hello-World/pulls/1/comments" } }, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } } ] # Commits /commits: type: item get: description: List commits on a pull request. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "sha": { "type": "string" }, "commit": { "properties": { "url": { "type": "string" }, "author": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "type": "object" }, "committer": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "tree": { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } }, "author": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } ], "type": "array" }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "commit": { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "author": { "name": "Monalisa Octocat", "email": "support@github.com", "date": "2011-04-14T16:00:49Z" }, "committer": { "name": "Monalisa Octocat", "email": "support@github.com", "date": "2011-04-14T16:00:49Z" }, "message": "Fix all the bugs", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } }, "author": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "committer": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } ] } ] /merge: type: base get: description: Get if a pull request has been merged. responses: 204: description: Pull request has been merged. 404: description: Pull request has not been merged. put: description: Merge a pull request (Merge Button™) body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "commit_message": { "description": "The message that will be used for the merge commit", "type": "string" } } } responses: 200: description: Response if merge was successful. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" }, "merged": { "type": "boolean" }, "message": { "type": "string" } } } example: | { "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "merged": true, "message": "Pull Request successfully merged" } 405: description: Response if merge cannot be performed. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" }, "merged": { "type": "boolean" }, "message": { "type": "string" } } } example: | { "sha": null, "merged": false, "message": "Failure reason" } /comments: type: collection get: description: List comments on a pull request. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } post: description: | Create a comment. #TODO Alternative input ( http://developer.github.com/v3/pulls/comments/ ) description: | Alternative Input. Instead of passing commit_id, path, and position you can reply to an existing Pull Request Comment like this: body Required string in_reply_to Required number - Comment id to reply to. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "body": { "type": "string" }, "commit_id": { "description": "Sha of the commit to comment on.", "type": "string" }, "path": { "description": "Relative path of the file to comment on.", "type": "string" }, "position": { "description": "Line index in the diff to comment on.", "type": "string" } }, "required": [ "body", "commit_id", "path", "position" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } /comments: type: collection get: description: | List comments in a repository. By default, Review Comments are ordered by ascending ID. queryParameters: sort: enum: - created - updated direction: description: Ignored without 'sort' parameter. enum: - asc - desc since: description: Timestamp in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ type: string responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } ] /{number}: uriParameters: number: description: Id of the comment. type: integer type: item get: description: Get a single comment. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } patch: description: Edit a comment. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "_links": { "properties": { "self": { "properties": { "href": { "type": "string" } }, "type": "object" }, "html": { "properties": { "href": { "type": "string" } }, "type": "object" }, "pull_request": { "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "_links": { "self": { "href": "https://api.github.com/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/octocat/Hello-World/pulls/1" } } } delete: description: Delete a comment. /collaborators: type: collection get: description: | List. When authenticating as an organization owner of an organization-owned repository, all organization owners are included in the list of collaborators. Otherwise, only users with access to the repository are returned in the collaborators list. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] /{user}: uriParameters: user: description: Login of the user. type: string type: base get: description: Check if user is a collaborator responses: 204: description: User is a collaborator. 404: description: User is not a collaborator. put: description: Add collaborator. responses: 204: description: Collaborator added. delete: description: Remove collaborator. responses: 204: description: Collaborator removed. /comments: type: collection get: description: | List commit comments for a repository. Comments are ordered by ascending ID. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "html_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "line": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1", "url": "https://api.github.com/repos/octocat/Hello-World/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "line": 14, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } ] /{commentId}: uriParameters: commentId: description: Id of a comment. type: integer type: item get: description: Get a single commit comment. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "html_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "line": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1", "url": "https://api.github.com/repos/octocat/Hello-World/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "line": 14, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } patch: description: Update a commit comment. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "html_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "line": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1", "url": "https://api.github.com/repos/octocat/Hello-World/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "line": 14, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } delete: description: Delete a commit comment /commits: type: collection get: description: List commits on a repository. queryParameters: sha: description: Sha or branch to start listing commits from. type: string path: description: Only commits containing this file path will be returned. type: string author: description: GitHub login, name, or email by which to filter by commit author. type: string since: description: ISO 8601 Date - Only commits after this date will be returned. type: string until: description: ISO 8601 Date - Only commits before this date will be returned. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "sha": { "type": "string" }, "commit": { "properties": { "url": { "type": "string" }, "author": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "type": "object" }, "committer": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "tree": { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } }, "author": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } ], "type": "array" }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "commit": { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "author": { "name": "Monalisa Octocat", "email": "support@github.com", "date": "2011-04-14T16:00:49Z" }, "committer": { "name": "Monalisa Octocat", "email": "support@github.com", "date": "2011-04-14T16:00:49Z" }, "message": "Fix all the bugs", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } }, "author": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "committer": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } ] } ] /{shaCode}: uriParameters: shaCode: description: SHA-1 code of the commit. type: string type: item get: description: Get a single commit. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "sha": { "type": "string" }, "commit": { "properties": { "url": { "type": "string" }, "author": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "type": "object" }, "committer": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "date": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "tree": { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } }, "author": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } ], "type": "array" } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "commit": { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "author": { "name": "Monalisa Octocat", "email": "support@github.com", "date": "2011-04-14T16:00:49Z" }, "committer": { "name": "Monalisa Octocat", "email": "support@github.com", "date": "2011-04-14T16:00:49Z" }, "message": "Fix all the bugs", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } }, "author": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "committer": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } ], "stats": { "additions": 104, "deletions": 4, "total": 108 }, "files": [ { "filename": "file1.txt", "additions": 10, "deletions": 2, "changes": 12, "status": "modified", "raw_url": "https://github.com/octocat/Hello-World/raw/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt", "blob_url": "https://github.com/octocat/Hello-World/blob/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt", "patch": "@@ -29,7 29,7 @@\n....." } ] } /comments: type: collection get: description: List comments for a single commitList comments for a single commit. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "html_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "line": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1", "url": "https://api.github.com/repos/octocat/Hello-World/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "line": 14, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } ] post: description: Create a commit comment. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "description": "SHA of the commit to comment on.", "type": "string" }, "body": { "type": "string" }, "path": { "description": "Relative path of the file to comment on.", "type": "string" }, "position": { "description": "Line index in the diff to comment on.", "type": "integer" }, "line": { "description": "Deprecated - Use position parameter instead.", "type": "string" }, "number": { "description": "Line number in the file to comment on. Defaults to null.", "type": "string" } }, "required": [ "sha", "body" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "html_url": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "integer" }, "body": { "type": "string" }, "path": { "type": "string" }, "position": { "type": "integer" }, "line": { "type": "integer" }, "commit_id": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1", "url": "https://api.github.com/repos/octocat/Hello-World/comments/1", "id": 1, "body": "Great stuff", "path": "file1.txt", "position": 4, "line": 14, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z" } /contents/{path}: uriParameters: path: type: string type: base get: description: | Get contents. This method returns the contents of a file or directory in a repository. Files and symlinks support a custom media type for getting the raw content. Directories and submodules do not support custom media types. Note: This API supports files up to 1 megabyte in size. Here can be many outcomes. For details see "http://developer.github.com/v3/repos/contents/" queryParameters: path: description: The content path. type: string ref: description: The String name of the Commit/Branch/Tag. Defaults to 'master'. type: string responses: 200: body: application/json: #TODO many outcomes schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "type": "string" }, "encoding": { "type": "string" }, "size": { "type": "integer" }, "name": { "type": "string" }, "path": { "type": "string" }, "content": { "type": "string" }, "sha": { "type": "string" }, "url": { "type": "string" }, "git_url": { "type": "string" }, "html_url": { "type": "string" }, "_links": { "properties": { "git": { "type": "string" }, "self": { "type": "string" }, "html": { "type": "string" } }, "type": "object" } } } example: | { "type": "file", "encoding": "base64", "size": 5362, "name": "README.md", "path": "README.md", "content": "encoded content ...", "sha": "3d21ec53a331a6f037a91c368710b99387d012c1", "url": "https://api.github.com/repos/pengwynn/octokit/contents/README.md", "git_url": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1", "html_url": "https://github.com/pengwynn/octokit/blob/master/README.md", "_links": { "git": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1", "self": "https://api.github.com/repos/pengwynn/octokit/contents/README.md", "html": "https://github.com/pengwynn/octokit/blob/master/README.md" } } put: description: Create a file. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "content": { "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "sha": { "type": "string" }, "size": { "type": "integer" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "git_url": { "type": "string" }, "type": { "type": "string" }, "_links": { "properties": { "self": { "type": "string" }, "git": { "type": "string" }, "html": { "type": "string" } }, "type": "object" } }, "type": "object" }, "commit": { "properties": { "sha": { "type": "string" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "author": { "properties": { "date": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "date": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "tree": { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } ] }, "type": "object" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "path": { "description": "The content path.", "type": "string" }, "message": { "description": "The commit message.", "type": "string" }, "content": { "description": "The new file content, Base64 encoded.", "type": "string" }, "sha": { "description": "Is included if we want to modify existing file. The blob SHA of the file being replaced.", "type": "string" }, "branch": { "description": "The branch name. If not provided, uses the repository's default branch (usually master).", "type": "string" }, "author": { "properties": { "name": { "description": "The name of the author of the commit.", "type": "string" }, "email": { "description": "The email of the author of the commit", "type": "string" } }, "type": "object" }, "committer": { "properties": { "name": { "description": "The name of the committer of the commit.", "type": "string" }, "email": { "description": "The email of the committer of the commit.", "type": "string" } }, "type": "object" } }, "required": [ "path", "message", "content", "branch" ] } example: | { "content": { "name": "hello.txt", "path": "notes/hello.txt", "sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3", "size": 9, "url": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt", "html_url": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt", "git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3", "type": "file", "_links": { "self": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt", "git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3", "html": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt" } }, "commit": { "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "html_url": "https://github.com/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2010-04-10T14:10:01-07:00", "name": "Scott Chacon", "email": "schacon@gmail.com" }, "committer": { "date": "2010-04-10T14:10:01-07:00", "name": "Scott Chacon", "email": "schacon@gmail.com" }, "message": "my commit message", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb", "sha": "691272480426f78a0138979dd3ce63b77f706feb" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5", "html_url": "https://github.com/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5", "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5" } ] } } delete: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "path": { "description": "The content path.", "type": "string" }, "message": { "description": "The commit message.", "type": "string" }, "content": { "description": "The new file content, Base64 encoded.", "type": "string" }, "sha": { "description": "The blob SHA of the file being removed.", "type": "string" }, "branch": { "description": "The branch name. If not provided, uses the repository's default branch (usually master).", "type": "string" }, "author": { "properties": { "name": { "description": "The name of the author of the commit.", "type": "string" }, "email": { "description": "The email of the author of the commit", "type": "string" } }, "type": "object" }, "committer": { "properties": { "name": { "description": "The name of the committer of the commit.", "type": "string" }, "email": { "description": "The email of the committer of the commit.", "type": "string" } }, "type": "object" } }, "required": [ "path", "message", "sha" ] } description: | Delete a file. This method deletes a file in a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "content": { "type": "string" }, "commit": { "properties": { "sha": { "type": "string" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "author": { "properties": { "date": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "committer": { "date": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "message": { "type": "string" }, "tree": { "properties": { "url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "sha": { "type": "string" } }, "type": "object" } ] }, "type": "object" } } } example: | { "content": null, "commit": { "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "html_url": "https://github.com/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2010-04-10T14:10:01-07:00", "name": "Scott Chacon", "email": "schacon@gmail.com" }, "committer": { "date": "2010-04-10T14:10:01-07:00", "name": "Scott Chacon", "email": "schacon@gmail.com" }, "message": "my commit message", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb", "sha": "691272480426f78a0138979dd3ce63b77f706feb" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5", "html_url": "https://github.com/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5", "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5" } ] } } /{archive_format}/{path}: type: base uriParameters: archive_format: enum: - tarball - zipball required: true path: description: Valid Git reference, defaults to 'master'. type: string get: description: | Get archive link. This method will return a 302 to a URL to download a tarball or zipball archive for a repository. Please make sure your HTTP framework is configured to follow redirects or you will need to use the Location header to make a second GET request. Note: For private repositories, these links are temporary and expire quickly. responses: 302: description: Found. /downloads: type: collection get: description: List downloads for a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "size": { "type": "integer" }, "download_count": { "type": "integer" }, "content_type": { "type": "string" } }, "type": "object" } ] } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/downloads/1", "html_url": "https://github.com/repos/octocat/Hello-World/downloads/new_file.jpg", "id": 1, "name": "new_file.jpg", "description": "Description of your download", "size": 1024, "download_count": 40, "content_type": ".jpg" } post: description: | Create a new download (Part 1: Create the resource). For part 2 see http://developer.github.com/v3/repos/downloads/#create-a-new-download-part-2-upload-file-to-s3 body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "size": { "description": "Size of file in bytes.", "type": "integer" }, "description": { "type": "string" }, "content_type": { "type": "string" } }, "required": [ "name", "size" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "size": { "type": "integer" }, "download_count": { "type": "integer" }, "content_type": { "type": "string" }, "policy": { "type": "string" }, "signature": { "type": "string" }, "bucket": { "type": "string" }, "accesskeyid": { "type": "string" }, "path": { "type": "string" }, "acl": { "type": "string" }, "expirationdate": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "prefix": { "type": "string" }, "mime_type": { "type": "string" }, "redirect": { "type": "boolean" }, "s3_url": { "type": "string" } } } example: | { "url": "https://api.github.com/repos/octocat/Hello-World/downloads/1", "html_url": "https://github.com/repos/octocat/Hello-World/downloads/new_file.jpg", "id": 1, "name": "new_file.jpg", "description": "Description of your download", "size": 1024, "download_count": 40, "content_type": ".jpg", "policy": "ewogICAg...", "signature": "mwnFDC...", "bucket": "github", "accesskeyid": "1ABCDEFG...", "path": "downloads/octocat/Hello-World/new_file.jpg", "acl": "public-read", "expirationdate": "2011-04-14T16:00:49Z", "prefix": "downloads/octocat/Hello-World/", "mime_type": "image/jpeg", "redirect": false, "s3_url": "https://github.s3.amazonaws.com/" } /{downloadId}: type: item uriParameters: downloadId: description: Id of the download. type: integer get: description: Get a single download. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "size": { "type": "integer" }, "download_count": { "type": "integer" }, "content_type": { "type": "string" } }, "type": "object" } ] } example: | delete: description: Delete a download. /forks: type: collection get: description: List forks. queryParameters: sort: enum: - newest - oldest - watchers default: newest responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] post: description: | Create a fork. Forking a Repository happens asynchronously. Therefore, you may have to wait a short period before accessing the git objects. If this takes longer than 5 minutes, be sure to contact Support. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "organization": { "description": "Organization login. The repository will be forked into this organization.", "type": "string" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } } } example: | { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } /keys: type: collection get: description: Get list of keys. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } ] post: description: Create a key. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "key": { "type": "string" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } example: | { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } /{keyId}: uriParameters: keyId: description: Id of a key. type: integer type: item get: description: Get a key responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } example: | { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } patch: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "key": { "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } example: | { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } description: Edit a key. delete: description: Delete a key. /hooks: type: collection get: description: Get list of hooks. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "name": { "type": "string" }, "events": [ { "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "active": { "type": "boolean" }, "config": { "properties": { "url": { "type": "string" }, "content_type": { "type": "string" } }, "type": "object" }, "id": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1", "updated_at": "2011-09-06T20:39:23Z", "created_at": "2011-09-06T17:26:27Z", "name": "web", "events": [ "push", "pull_request" ], "active": true, "config": { "url": "http://example.com", "content_type": "json" }, "id": 1 } ] post: description: Create a hook. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "config": { "description": "A Hash containing key/value pairs to provide settings for this hook. Modifying this will replace the entire config object. These settings vary between the services and are defined in the github-services repo. Booleans are stored internally as \"1\" for true, and \"0\" for false. Any JSON true/false values will be converted automatically.", "type": "string" }, "events": [ { "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "add_events": [ { "description": "Determines a list of events to be added to the list of events that the Hook triggers for.", "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "remove_events": [ { "description": "Determines a list of events to be removed from the list of events that the Hook triggers for.", "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "active": { "description": "Determines whether the hook is actually triggered on pushes.", "type": "boolean" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "name": { "type": "string" }, "events": [ { "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "active": { "type": "boolean" }, "config": { "properties": { "url": { "type": "string" }, "content_type": { "type": "string" } }, "type": "object" }, "id": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1", "updated_at": "2011-09-06T20:39:23Z", "created_at": "2011-09-06T17:26:27Z", "name": "web", "events": [ "push", "pull_request" ], "active": true, "config": { "url": "http://example.com", "content_type": "json" }, "id": 1 } ] /{hookId}: uriParameters: hookId: description: Id of the hook. type: integer type: item get: description: Get single hook. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "name": { "type": "string" }, "events": [ { "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "active": { "type": "boolean" }, "config": { "properties": { "url": { "type": "string" }, "content_type": { "type": "string" } }, "type": "object" }, "id": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1", "updated_at": "2011-09-06T20:39:23Z", "created_at": "2011-09-06T17:26:27Z", "name": "web", "events": [ "push", "pull_request" ], "active": true, "config": { "url": "http://example.com", "content_type": "json" }, "id": 1 } ] patch: description: Edit a hook. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "config": { "description": "A Hash containing key/value pairs to provide settings for this hook. Modifying this will replace the entire config object. These settings vary between the services and are defined in the github-services repo. Booleans are stored internally as \"1\" for true, and \"0\" for false. Any JSON true/false values will be converted automatically.", "type": "string" }, "events": [ { "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "add_events": [ { "description": "Determines a list of events to be added to the list of events that the Hook triggers for.", "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "remove_events": [ { "description": "Determines a list of events to be removed from the list of events that the Hook triggers for.", "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "active": { "description": "Determines whether the hook is actually triggered on pushes.", "type": "boolean" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "url": { "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "name": { "type": "string" }, "events": [ { "enum": [ "push", "issues", "issue_comment", "commit_comment", "pull_request", "pull_request_review_comment", "gollum", "watch", "download", "fork", "fork_apply", "member", "public", "team_add", "status" ] } ], "type": "array", "active": { "type": "boolean" }, "config": { "properties": { "url": { "type": "string" }, "content_type": { "type": "string" } }, "type": "object" }, "id": { "type": "integer" } } } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1", "updated_at": "2011-09-06T20:39:23Z", "created_at": "2011-09-06T17:26:27Z", "name": "web", "events": [ "push", "pull_request" ], "active": true, "config": { "url": "http://example.com", "content_type": "json" }, "id": 1 } ] delete: description: Delete a hook. /tests: type: base post: description: | Test a push hook. This will trigger the hook with the latest push to the current repository if the hook is subscribed to push events. If the hook is not subscribed to push events, the server will respond with 204 but no test POST will be generated. Note: Previously /repos/:owner/:repo/hooks/:id/test responses: 204: description: Hook is triggered. /merges: type: base post: description: Perform a merge. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "base": { "description": "The name of the base branch that the head will be merged into.", "type": "string" }, "head": { "description": "The head to merge. This can be a branch name or a commit SHA1.", "type": "string" }, "commit_message": { "description": "Commit message to use for the merge commit. If omitted, a default message will be used.", "type": "string" } }, "required": [ "base", "head" ] } responses: 201: description: Successful Response (The resulting merge commit) body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "sha": { "type": "string" }, "commit": { "properties": { "author": { "properties": { "name": { "type": "string" }, "date": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "name": { "type": "string" }, "date": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "tree": { "properties": { "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "url": { "type": "string" }, "comment_count": { "type": "integer" } }, "type": "object" }, "url": { "type": "string" }, "comments_url": { "type": "string" }, "author": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "followers_url": { "type": "string" }, "following_url": { "type": "string" }, "gists_url": { "type": "string" }, "starred_url": { "type": "string" }, "subscriptions_url": { "type": "string" }, "organizations_url": { "type": "string" }, "repos_url": { "type": "string" }, "events_url": { "type": "string" }, "received_events_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "committer": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "followers_url": { "type": "string" }, "following_url": { "type": "string" }, "gists_url": { "type": "string" }, "starred_url": { "type": "string" }, "subscriptions_url": { "type": "string" }, "organizations_url": { "type": "string" }, "repos_url": { "type": "string" }, "events_url": { "type": "string" }, "received_events_url": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "parents": [ { "properties": { "sha": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ], "type": "array" } } example: | { "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "merged": true, "message": "Pull Request successfully merged" } 204: description: No-op response (base already contains the head, nothing to merge) 409: description: Merge conflict response. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "message": { "description": "Error message", "type": "string" } } } example: | { "message": "Merge Conflict" } 404: description: Missing base response or missing head response body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "message": { "description": "Error message", "type": "string" } } } example: | { "message": "Base does not exist" } /statuses/{ref}: type: collection uriParameters: ref: description: | Ref to list the statuses from. It can be a SHA, a branch name, or a tag name. type: string get: description: List Statuses for a specific Ref. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "state": { "type": "string" }, "target_url": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "state": "success", "target_url": "https://ci.example.com/1000/output", "description": "Build has completed successfully", "id": 1, "url": "https://api.github.com/repos/octocat/example/statuses/1", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } } ] post: description: Create a Status. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "state": { "enum": [ "pending", "success", "error", "failure" ] }, "target_url": { "description": "Target url to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the ?source' of the Status.", "type": "string" }, "description": { "description": "Short description of the status", "type": "string" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "state": { "type": "string" }, "target_url": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } example: | [ { "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "state": "success", "target_url": "https://ci.example.com/1000/output", "description": "Build has completed successfully", "id": 1, "url": "https://api.github.com/repos/octocat/example/statuses/1", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } } ] /stats: /contributors: type: collection get: description: Get contributors list with additions, deletions, and commit counts. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "author": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "total": { "description": "The Total number of commits authored by the contributor.", "type": "integer" }, "weeks": [ { "properties": { "w": { "description": "Start of the week.", "type": "string" }, "a": { "description": "Number of additions.", "type": "integer" }, "d": { "description": "Number of deletions.", "type": "integer" }, "c": { "description": "Number of commits.", "type": "integer" } }, "type": "object" } ], "type": "array" } ] } example: | [ { "author": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "total": 135, "weeks": [ { "w": "1367712000", "a": 6898, "d": 77, "c": 10 } ] } ] /commit_activity: type: collection get: description: | Get the last year of commit activity data. Returns the last year of commit activity grouped by week. The days array is a group of commits per day, starting on Sunday. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "days": [ { "type": "integer" } ], "type": "array", "total": { "type": "integer" }, "week": { "type": "integer" } }, "type": "object" } ] } example: | [ { "days": [ 0, 3, 26, 20, 39, 1, 0 ], "total": 89, "week": 1336280400 } ] /code_frequency: type: collection get: description: | Get the number of additions and deletions per week. Returns a weekly aggregate of the number of additions and deletions pushed to a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "type": "integer" } ] } example: | [ [ 1302998400, 1124, -435 ] ] /participation: type: collection get: description: Get the weekly commit count for the repo owner and everyone else. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "all": [ { "type": "integer" } ], "type": "array", "owner": [ { "type": "integer" } ], "type": "array" } } example: | { "all": [ 11, 21, 15, 2, 8, 1, 8, 23, 17, 21, 11, 10, 33, 91, 38, 34, 22, 23, 32, 3, 43, 87, 71, 18, 13, 5, 13, 16, 66, 27, 12, 45, 110, 117, 13, 8, 18, 9, 19, 26, 39, 12, 20, 31, 46, 91, 45, 10, 24, 9, 29, 7 ], "owner": [ 3, 2, 3, 0, 2, 0, 5, 14, 7, 9, 1, 5, 0, 48, 19, 2, 0, 1, 10, 2, 23, 40, 35, 8, 8, 2, 10, 6, 30, 0, 2, 9, 53, 104, 3, 3, 10, 4, 7, 11, 21, 4, 4, 22, 26, 63, 11, 2, 14, 1, 10, 3 ] } /punch_card: type: collection get: description: | Get the number of commits per hour in each day. Each array contains the day number, hour number, and number of commits 0-6 Sunday - Saturday 0-23 Hour of day Number of commits For example, [2, 14, 25] indicates that there were 25 total commits, during the 2.00pm hour on Tuesdays. All times are based on the time zone of individual commits. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "": [ { "type": "integer" } ] } ] } example: | [ [ 0, 0, 5 ], [ 0, 1, 43 ], [ 0, 2, 21 ] ] /user: type: item get: description: Get the authenticated user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "blog": { "type": "string" }, "location": { "type": "string" }, "email": { "type": "string" }, "hireable": { "type": "boolean" }, "bio": { "type": "string" }, "public_repos": { "type": "integer" }, "public_gists": { "type": "integer" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "html_url": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "type": { "type": "string" }, "total_private_repos": { "type": "integer" }, "owned_private_repos": { "type": "integer" }, "private_gists": { "type": "integer" }, "disk_usage": { "type": "integer" }, "collaborators": { "type": "integer" }, "plan": { "properties": { "name": { "type": "string" }, "space": { "type": "integer" }, "collaborators": { "type": "integer" }, "private_repos": { "type": "integer" } }, "type": "object" } } } example: | { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "name": "monalisa octocat", "company": "GitHub", "blog": "https://github.com/blog", "location": "San Francisco", "email": "octocat@github.com", "hireable": false, "bio": "There once was...", "public_repos": 2, "public_gists": 1, "followers": 20, "following": 0, "html_url": "https://github.com/octocat", "created_at": "2008-01-14T04:33:35Z", "type": "User", "total_private_repos": 100, "owned_private_repos": 100, "private_gists": 81, "disk_usage": 10000, "collaborators": 8, "plan": { "name": "Medium", "space": 400, "collaborators": 10, "private_repos": 20 } } patch: description: Update the authenticated user. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "blog": { "type": "string" }, "company": { "type": "string" }, "location": { "type": "string" }, "hireable": { "type": "boolean" }, "bio": { "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "blog": { "type": "string" }, "location": { "type": "string" }, "email": { "type": "string" }, "hireable": { "type": "boolean" }, "bio": { "type": "string" }, "public_repos": { "type": "integer" }, "public_gists": { "type": "integer" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "html_url": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "type": { "type": "string" }, "total_private_repos": { "type": "integer" }, "owned_private_repos": { "type": "integer" }, "private_gists": { "type": "integer" }, "disk_usage": { "type": "integer" }, "collaborators": { "type": "integer" }, "plan": { "properties": { "name": { "type": "string" }, "space": { "type": "integer" }, "collaborators": { "type": "integer" }, "private_repos": { "type": "integer" } }, "type": "object" } } } example: | { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "name": "monalisa octocat", "company": "GitHub", "blog": "https://github.com/blog", "location": "San Francisco", "email": "octocat@github.com", "hireable": false, "bio": "There once was...", "public_repos": 2, "public_gists": 1, "followers": 20, "following": 0, "html_url": "https://github.com/octocat", "created_at": "2008-01-14T04:33:35Z", "type": "User", "total_private_repos": 100, "owned_private_repos": 100, "private_gists": 81, "disk_usage": 10000, "collaborators": 8, "plan": { "name": "Medium", "space": 400, "collaborators": 10, "private_repos": 20 } } /orgs: type: collection get: description: List public and private organizations for the authenticated user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "login": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "avatar_url": { "type": "string" } } ] } example: | [ { "login": "github", "id": 1, "url": "https://api.github.com/orgs/github", "avatar_url": "https://github.com/images/error/octocat_happy.gif" } ] # Other /{userId}: type: collection uriParameters: userId: type: integer get: securedBy: [ oauth_2_0, null ] description: Get a single user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "blog": { "type": "string" }, "location": { "type": "string" }, "email": { "description": "Note: The returned email is the user's publicly visible email address (or null if the user has not specified a public email address in their profile).", "type": "string" }, "hireable": { "type": "boolean" }, "bio": { "type": "string" }, "public_repos": { "type": "integer" }, "public_gists": { "type": "integer" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "html_url": { "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "type": { "type": "string" } } } example: | { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat", "name": "monalisa octocat", "company": "GitHub", "blog": "https://github.com/blog", "location": "San Francisco", "email": "octocat@github.com", "hireable": false, "bio": "There once was...", "public_repos": 2, "public_gists": 1, "followers": 20, "following": 0, "html_url": "https://github.com/octocat", "created_at": "2008-01-14T04:33:35Z", "type": "User" } # Received events /received_events: type: collection get: description: List events that a user has received. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] /public: type: collection get: description: List public events that a user has received. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] # Orgs /orgs: type: collection get: description: List all public organizations for a user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "login": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "avatar_url": { "type": "string" } } ] } example: | [ { "login": "github", "id": 1, "url": "https://api.github.com/orgs/github", "avatar_url": "https://github.com/images/error/octocat_happy.gif" } ] /events: type: collection get: description: | List events performed by a user. If you are authenticated as the given user, you will see your private events. Otherwise, you'll only see public events. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] # Public /public: type: collection get: description: List public events performed by a user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] # Orgs events /orgs/{orgId}: uriParameters: orgId: type: integer type: collection get: description: List events for an organization. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] /starred: type: collection get: description: List repositories being starred. queryParameters: sort: enum: - created - updated default: created direction: enum: - asc - desc default: desc responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /subscriptions: type: collection get: description: List repositories being watched by a user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "integer" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /emails: type: collection get: description: | List email addresses for a user. In the final version of the API, this method will return an array of hashes with extended information for each email address indicating if the address has been verified and if it's the user's primary email address for GitHub. Until API v3 is finalized, use the application/vnd.github.v3 media type to get other response format. responses: 200: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "type": "string" } ] } example: | [ "octocat@github.com", "support@github.com" ] application/vnd.github.v3: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "properties": { "email": { "type": "string" }, "verified": { "type": "boolean" }, "primary": { "type": "boolean" } }, "type": "object" } ] } example: | [ { "email": "octocat@github.com", "verified": true, "primary": true } ] post: description: | Add email address(es). You can post a single email address or an array of addresses. delete: description: | Delete email address(es). You can include a single email address or an array of addresses. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "type": "string" } ] } /following: type: collection get: description: List who the authenticated user is following. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] /{userId}: uriParameters: userId: type: integer type: base get: description: Check if you are following a user. responses: 204: description: Response if you are following this user. 404: description: Response if you are not following this user. put: description: | Follow a user. Following a user requires the user to be logged in and authenticated with basic auth or OAuth with the user:follow scope. responses: 204: description: You are now following the user. delete: description: | Unfollow a user. Unfollowing a user requires the user to be logged in and authenticated with basic auth or OAuth with the user:follow scope. responses: 204: description: User unfollowed. /keys: type: collection get: description: | List your public keys. Lists the current user's keys. Management of public keys via the API requires that you are authenticated through basic auth, or OAuth with the 'user' scope. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } ] post: description: Create a public key. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "key": { "type": "string" } } } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } example: | { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } /{keyId}: uriParameters: keyId: type: integer type: item get: description: Get a single public key. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } example: | { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } patch: description: Update a public key. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "title": { "type": "string" }, "key": { "type": "string" } } } responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } example: | { "id": 1, "key": "ssh-rsa AAA...", "url": "https://api.github.com/user/keys/1", "title": "octocat@octomac" } delete: description: Delete a public key. /starred: type: collection get: description: List repositories being starred by the authenticated user. queryParameters: sort: enum: - created - updated default: created direction: enum: - asc - desc default: desc responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /{ownerId}/{repoId}: type: base get: description: Check if you are starring a repository. responses: 204: description: This repository is starred by you. 404: description: This repository is not starred by you. put: description: Star a repository. responses: 204: description: Repository starred. delete: description: Unstar a repository responses: 204: description: Unstarred. /subscriptions: type: collection get: description: List repositories being watched by the authenticated user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "integer" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /{ownerId}/{repoId}: type: base uriParameters: ownerId: description: Id of the owner. type: integer repoId: description: Id of repository. type: integer get: description: Check if you are watching a repository. responses: 204: description: Repository is watched by you. 404: description: Repository is not watched by you. put: description: Watch a repository. responses: 204: description: Repository is watched. delete: description: Stop watching a repository responses: 204: description: Unwatched. /issues: type: collection get: is: [ filterable ] description: | List issues. List all issues across owned and member repositories for the authenticated user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "issues": [ { "properties": { "url": { "type": "string" }, "html_url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "labels": [ { "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" } ], "type": "array", "assignee": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "milestone": { "properties": { "url": { "type": "string" }, "number": { "type": "integer" }, "state": { "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "creator": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "open_issues": { "type": "integer" }, "closed_issues": { "type": "integer" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "due_on": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" }, "comments": { "type": "integer" }, "pull_request": { "properties": { "html_url": { "type": "string" }, "diff_url": { "type": "string" }, "patch_url": { "type": "string" } }, "type": "object" }, "closed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } example: | [ { "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347", "html_url": "https://github.com/octocat/Hello-World/issues/1347", "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "labels": [ { "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug", "name": "bug", "color": "f29513" } ], "assignee": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "milestone": { "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1", "number": 1, "state": "open", "title": "v1.0", "description": "", "creator": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "open_issues": 4, "closed_issues": 8, "created_at": "2011-04-10T20:09:31Z", "due_on": null }, "comments": 0, "pull_request": { "html_url": "https://github.com/octocat/Hello-World/issues/1347", "diff_url": "https://github.com/octocat/Hello-World/issues/1347.diff", "patch_url": "https://github.com/octocat/Hello-World/issues/1347.patch" }, "closed_at": null, "created_at": "2011-04-22T13:33:48Z", "updated_at": "2011-04-22T13:33:48Z" } ] /repos: type: collection get: description: | List repositories for the authenticated user. Note that this does not include repositories owned by organizations which the user can access. You can list user organizations and list organization repositories separately. queryParameters: type: enum: - all - public - private - forks - sources - member default: all responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] post: description: | Create a new repository for the authenticated user. OAuth users must supply repo scope. body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "homepage": { "type": "string" }, "private": { "description": "True to create a private repository, false to create a public one. Creating private repositories requires a paid GitHub account.", "type": "boolean" }, "has_issues": { "description": "True to enable issues for this repository, false to disable them. Default is true.", "type": "boolean" }, "has_wiki": { "description": "True to enable the wiki for this repository, false to disable it. Default is true.", "type": "boolean" }, "has_downloads": { "description": "True to enable downloads for this repository, false to disable them. Default is true.", "type": "boolean" }, "team_id": { "description": "The id of the team that will be granted access to this repository. This is only valid when creating a repo in an organization.", "type": "integer" }, "auto_init": { "description": "True to create an initial commit with empty README. Default is false.", "type": "boolean" }, "gitignore_template": { "description": "Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, \"Haskell\" Ignored if auto_init parameter is not provided. ", "type": "string" } }, "required": [ "name" ] } responses: 201: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /users: type: collection get: description: | Get all users. This provides a dump of every user, in the order that they signed up for GitHub. Note: Pagination is powered exclusively by the since parameter. Use the Link header to get the URL for the next page of users. queryParameters: since: description: The integer ID of the last User that you've seen. type: integer responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] /{userId}: uriParameters: userId: type: integer type: collection get: description: List a user's followers. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "list": [ { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } ] } example: | [ { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" } ] # Followers /following/{targetUserId}: uriParameters: targetUserId: type: integer type: base get: description: Check if one user follows another. responses: 204: description: Response if user follows target user. 404: description: Response if user does not follow target user. # Keys /keys: type: collection get: description: | List public keys for a user. Lists the verified public keys for a user. This is accessible by anyone. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "id": { "type": "integer" }, "key": { "type": "string" } } ] } example: | [ { "id": 1, "key": "ssh-rsa AAA..." } ] # Gists /gists: type: collection get: securedBy: [ null, oauth_2_0 ] description: List a user's gists. queryParameters: since: description: | Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned. type: string responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "gists": [ { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "description": { "type": "string" }, "public": { "type": "boolean" }, "user": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "files": { "properties": { "ring.erl": { "properties": { "size": { "type": "integer" }, "filename": { "type": "string" }, "raw_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "comments": { "type": "integer" }, "comments_url": { "type": "string" }, "html_url": { "type": "string" }, "git_pull_url": { "type": "string" }, "git_push_url": { "type": "string" }, "created_at": { "type": "string" } } } ] } example: | [ { "url": "https://api.github.com/gists/20c98223d9b59e1d48e5", "id": "1", "description": "description of gist", "public": true, "user": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "files": { "ring.erl": { "size": 932, "filename": "ring.erl", "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl" } }, "comments": 0, "comments_url": "https://api.github.com/gists/19d18b30e8af75090307/comments/", "html_url": "https://gist.github.com/1", "git_pull_url": "git://gist.github.com/1.git", "git_push_url": "git@gist.github.com:1.git", "created_at": "2010-04-14T02:15:15Z" } ] /orgs: type: collection get: description: List all public organizations for a user. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "login": { "type": "string" }, "id": { "type": "integer" }, "url": { "type": "string" }, "avatar_url": { "type": "string" } } ] } example: | [ { "login": "github", "id": 1, "url": "https://api.github.com/orgs/github", "avatar_url": "https://github.com/images/error/octocat_happy.gif" } ] /repos: type: collection get: description: List public repositories for the specified user. queryParameters: type: enum: - all - public - private - forks - sources - member default: all responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "": [ { "properties": { "id": { "type": "integer" }, "owner": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "name": { "type": "string" }, "full_name": { "type": "string" }, "description": { "type": "string" }, "private": { "type": "boolean" }, "fork": { "type": "boolean" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "clone_url": { "type": "string" }, "git_url": { "type": "string" }, "ssh_url": { "type": "string" }, "svn_url": { "type": "string" }, "mirror_url": { "type": "string" }, "homepage": { "type": "string" }, "language": { "type": "string" }, "forks": { "type": "integer" }, "forks_count": { "type": "integer" }, "watchers": { "type": "integer" }, "watchers_count": { "type": "integer" }, "size": { "type": "integer" }, "master_branch": { "type": "string" }, "open_issues": { "type": "integer" }, "open_issues_count": { "type": "integer" }, "pushed_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "created_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" }, "updated_at": { "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ", "type": "string" } }, "type": "object" } ] } } example: | [ { "id": 1296269, "owner": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "This your first repo!", "private": false, "fork": true, "url": "https://api.github.com/repos/octocat/Hello-World", "html_url": "https://github.com/octocat/Hello-World", "clone_url": "https://github.com/octocat/Hello-World.git", "git_url": "git://github.com/octocat/Hello-World.git", "ssh_url": "git@github.com:octocat/Hello-World.git", "svn_url": "https://svn.github.com/octocat/Hello-World", "mirror_url": "git://git.example.com/octocat/Hello-World", "homepage": "https://github.com", "language": null, "forks": 9, "forks_count": 9, "watchers": 80, "watchers_count": 80, "size": 108, "master_branch": "master", "open_issues": 0, "open_issues_count": 0, "pushed_at": "2011-01-26T19:06:43Z", "created_at": "2011-01-26T19:01:12Z", "updated_at": "2011-01-26T19:14:43Z" } ] /gitignore/templates: type: collection get: description: | Listing available templates. List all templates available to pass as an option when creating a repository. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "": [ { "type": "string" } ] } example: | [ "Actionscript", "Android", "AppceleratorTitanium", "Autotools", "Bancha", "C", "C " ] /{language}: type: item uriParameters: language: type: string get: description: Get a single template. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "name": { "type": "string" }, "source": { "type": "string" } } } example: | { "name": "C", "source": "# Object files\n*.o\n\n# Libraries\n*.lib\n*.a\n\n# Shared objects (inc. Windows DLLs)\n*.dll\n*.so\n*.so.*\n*.dylib\n\n# Executables\n*.exe\n*.out\n*.app\n" } /markdown: type: base post: body: application/json: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "text": { "description": "The Markdown text to render", "type": "string" }, "mode": { "enum": [ "markdown", "gfm" ] }, "context": { "description": "The repository context, only taken into account when rendering as gfm.", "type": "string" } }, "required": [ "text" ] } responses: 200: body: text/html: example: |

Hello world github/linguist#1 cool, and #1!

/raw: type: base post: body: text/plain: example: |

Hello world github/linguist#1 cool, and #1!

responses: 200: body: text/html: example: |

Hello world github/linguist#1 cool, and #1!

/networks/{ownerId}/{repoId}/events: type: collection uriParameters: ownerId: description: Id of the owner. type: integer repoId: description: Id of repository. type: integer get: description: List public events for a network of repositories. responses: 200: body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "array", "properties": [ { "properties": { "type": { "type": "string" }, "public": { "type": "boolean" }, "payload": { "properties": {}, "type": "object" }, "repo": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "actor": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "org": { "properties": { "login": { "type": "string" }, "id": { "type": "integer" }, "avatar_url": { "type": "string" }, "gravatar_id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "id": { "type": "integer" } }, "type": "object" } ] } example: | [ { "type": "Event", "public": true, "payload": { }, "repo": { "id": 3, "name": "octocat/Hello-World", "url": "https://api.github.com/repos/octocat/Hello-World" }, "actor": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "org": { "login": "octocat", "id": 1, "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "somehexcode", "url": "https://api.github.com/users/octocat" }, "created_at": "2011-09-06T17:26:27Z", "id": "12345" } ] ================================================ FILE: samples/notes/api.raml ================================================ #%RAML 0.8 title: Notes Example API version: v2 mediaType: application/json documentation: - title: Overview content: This is an example of a simple API for a "notes" service /notes: description: A collection of notes get: description: List all notes, optionally filtered by a query string queryParameters: q: description: An optional search query to filter the results example: shopping responses: 200: body: text/json: example: | [ { "id": 1, "title": "Buy some milk", "status": "done" }, { "id": 2, "title": "Return sweater", "status": "overdue", "dueInDays": -2 }, { "id": 3, "title": "Renew license", "status": "not done", "dueInDays": 1 }, { "id": 4, "title": "Join gym", "status": "not done", "dueInDays": 3 } ] post: description: Create a new note in the collection body: example: | { "title": "Return sweater", "dueInDays": -2 } headers: X-Tracking-Example: description: You can specify request headers like this enum: [ accounting, payroll, finance ] required: false # require it by changing this to true example: accounting responses: 201: headers: X-Powered-By: description: You can describe response headers like this example: RAML body: text/json: example: | { "id": 2, "title": "Return sweater", "status": "overdue", "dueInDays": -2 } /{id}: description: A specific note, identified by its id uriParameters: id: description: The `id` of the specific note type: number example: 2 get: description: Retrieve the specified note responses: 200: text/json: body: example: | { "id": 2, "title": "Return sweater", "status": "overdue", "dueInDays": -2 } patch: description: Update the specified note (allowing partial information) body: text/json: example: | { "title": "Exchange sweater", "dueInDays: 3 } responses: 200: text/json: body: example: | { "id": 2, "title": "Exchange sweater", "status": "not done", "dueInDays": 3 } delete: description: Remove the specified note responses: 204: ================================================ FILE: samples/other_example.raml ================================================ #%RAML 0.8 title: Notes Example API mediaType: application/json documentation: - title: Overview content: This is an example of a simple API for a "notes" service - title: Explanation In Depth content: Enjoy this baseUri: /lala protocols: [HTTP, HTTPS] schemas: - schema1: "jsonStuff" schema2: "" - schema3: "another value" uriParameters: communityDomain: displayName: Community Domain type: string communityPath: displayName: Community Path type: string pattern: ^[a-zA-Z0-9][-a-zA-Z0-9]*$ minLength: 1 baseUriParameters: test: displayName: TEST PARAM description: a crazy description type: paramType pattern: regexpCRAZYNESS minLength: 10 maxLength: 20 minimum: 0.3 maximum: 0.5 repeat: true required: false default: "default string" example: 50 enum: [ example, 4, 0.3 ] apiDomain: description: | The sub-domain at which the API is accessible. Most API calls are sent to https://api.dropbox.com enum: [ "api" ] traits: - anothertrait: usage: any way you want it description: why yetanothertrait: usage: don't use it description: honestly, don't - testtrait: usage: use this trait so happilly description: Traits RULE queryParameters: test: displayName: TEST PARAM description: a crazy description type: paramType pattern: regexpCRAZYNESS minLength: 10 maxLength: 20 minimum: 0.3 maximum: 0.5 repeat: true required: false default: "default string" example: 50 enum: [ example, 4, 0.3 ] apiDomain: description: | The sub-domain at which the API is accessible. Most API calls are sent to https://api.dropbox.com enum: [ "api" ] body: application/json: schema: responseExampleJSON description: SDFSDF example: DFGD headers: header5: displayName: HEADER ONE header9: displayName: HEADER tWOOOOTWOTW application/xml: schema: responseExampleXML description: SDFSDF example: DFGD formParameters: formParam234: displayName: SO WORKS headers: header10: displayName: HEADER ONE header20: displayName: HEADER tWOOOOTWOTW headers: header1: displayName: HEADER ONE header2: displayName: HEADER tWOOOOTWOTW responses: 200: description: response200 headers: header1: displayName: HEADER ONE header2: displayName: HEADER tWOOOOTWOTW body: application/json: schema: responseExampleJSON description: SDFSDF example: DFGD headers: header5: displayName: HEADER ONE header9: displayName: HEADER tWOOOOTWOTW application/xml: schema: responseExampleXML description: SDFSDF example: DFGD formParameters: formParam234: displayName: SO WORKS headers: header10: displayName: HEADER ONE header20: displayName: HEADER tWOOOOTWOTW 404: description: response404 headers: header1: displayName: HEADER ONE header2: displayName: HEADER tWOOOOTWOTW body: application/json: schema: responseExampleJSON description: SDFSDF example: DFGD headers: header5: displayName: HEADER ONE header9: displayName: HEADER tWOOOOTWOTW application/xml: schema: responseExampleXML description: SDFSDF example: DFGD formParameters: formParam234: displayName: SO WORKS headers: header10: displayName: HEADER ONE header20: displayName: HEADER tWOOOOTWOTW resourceTypes: - rttest: description: test - one: description: hi two: description: bye get: description: test - collection: description: collectme get: responses: 200: body: application/json: schema: <> # e.g. users post: responses: 200: body: schema: <> # e.g. user image/jpeg: example: <> # e.g. user - member: description: memme get: responses: 200: body: schema: <> # e.g. user /jobs: displayName: Jobs post: description: Create a job body: text/xml: schema: schema1 # using a name from the root schemas ================================================ FILE: samples/raml-tutorial-200/README.md ================================================ raml-tutorial-200 ================= Step by step 200 raml tutorial code ================================================ FILE: samples/raml-tutorial-200/jukebox-api.raml ================================================ #%RAML 0.8 --- title: Jukebox API baseUri: http://jukebox.api.com version: v1 schemas: - song: !include jukebox-include-song.schema - artist: !include jukebox-include-artist.schema - album: !include jukebox-include-album.schema resourceTypes: - readOnlyCollection: description: Collection of available <> in Jukebox. get: description: Get a list of <>. responses: 200: body: application/json: example: | <> - collection: description: Collection of available <> in Jukebox. get: description: Get a list of <>. responses: 200: body: application/json: example: | <> post: description: | Add a new <> to Jukebox. queryParameters: access_token: description: "The access token provided by the authentication application" example: AABBCCDD required: true type: string body: application/json: schema: <> example: | <> responses: 200: body: application/json: example: | { "message": "The <> has been properly entered" } - collection-item: description: Entity representing a <> get: description: | Get the <> with <>Id = {<>Id} responses: 200: body: application/json: example: | <> 404: body: application/json: example: | {"message": "<> not found" } traits: - searchable: queryParameters: query: description: | JSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] <> example: | <> - orderable: queryParameters: orderBy: description: | Order by field: <> type: string required: false order: description: Order enum: [desc, asc] default: desc required: false - pageable: queryParameters: offset: description: Skip over a number of elements by specifying an offset value for the query type: integer required: false example: 20 default: 0 limit: description: Limit the number of elements on the response type: integer required: false example: 80 default: 10 /songs: type: collection: exampleCollection: !include jukebox-include-songs.sample exampleItem: !include jukebox-include-song-new.sample get: is: [ searchable: {description: "with valid searchable fields: songTitle", example: "[\"songTitle\", \"Get L\", \"like\"]"}, orderable: {fieldsList: "songTitle"}, pageable ] /{songId}: type: collection-item: exampleItem: !include jukebox-include-song-retrieve.sample /file-content: description: The file to be reproduced by the client get: description: Get the file content responses: 200: body: binary/octet-stream: example: !include heybulldog.mp3 post: description: | Enters the file content for an existing song entity. The song needs to be created for the `/songs/{songId}/file-content` to exist. You can use this second resource to get and post the file to reproduce. Use the "binary/octet-stream" content type to specify the content from any consumer (excepting web-browsers). Use the "multipart-form/data" content type to upload a file which content will become the file-content body: binary/octet-stream: multipart/form-data: formParameters: file: description: The file to be uploaded required: true type: file /artists: type: collection: exampleCollection: !include jukebox-include-artists.sample exampleItem: !include jukebox-include-artist-new.sample get: is: [ searchable: {description: "with valid searchable fields: countryCode", example: "[\"countryCode\", \"FRA\", \"equals\"]"}, orderable: {fieldsList: "artistName, nationality"}, pageable ] /{artistId}: type: collection-item: exampleItem: !include jukebox-include-artist-retrieve.sample /albums: type: readOnlyCollection: exampleCollection: !include jukebox-include-artist-albums.sample description: Collection of albulms belonging to the artist get: description: Get a specific artist's albums list is: [orderable: {fieldsList: "albumName"}, pageable] /albums: type: collection: exampleCollection: !include jukebox-include-albums.sample exampleItem: !include jukebox-include-album-new.sample get: is: [ searchable: {description: "with valid searchable fields: genreCode", example: "[\"genreCode\", \"ELE\", \"equals\"]"}, orderable: {fieldsList: "albumName, genre"}, pageable ] /{albumId}: type: collection-item: exampleItem: !include jukebox-include-album-retrieve.sample /songs: type: readOnlyCollection: exampleCollection: | !include jukebox-include-album-songs.sample get: is: [orderable: {fieldsList: "songTitle"}] description: Get the list of songs for the album with `albumId = {albumId}` ================================================ FILE: samples/raml-tutorial-200/jukebox-include-album-new.sample ================================================ '{ "albumId": "183100e3-0e2b-4404-a716-66104d440550", "albumName": "Random Access Memories", "year": "2013", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg", "genreCode": "ELE", "artistId": "110e8300-e32b-41d4-a716-664400445500" }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-album-retrieve.sample ================================================ '{ "albumId": "183100e3-0e2b-4404-a716-66104d440550", "albumName": "Random Access Memories", "year": "2013", "genre": "Electric Funk", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg", "genre": { "countryCode": "ELE", "countryName": "Electronict" }, "songs": [ { "songId": "550e8400-e29b-41d4-a716-446655440000", "songTitle": "Get Lucky" }, { "songId": "550e8400-e29b-41d4-a716-446655440111", "songTitle": "Loose yourself to dance" }, { "songId": "550e8400-e29b-41d4-a716-446655440222", "songTitle": "Gio sorgio by Moroder" } ], "artist": { "artistId": "110e8300-e32b-41d4-a716-664400445500", "artistName": "Daft Punk", "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg" } }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-album-songs.sample ================================================ [ { "songId": "550e8400-e29b-41d4-a716-446655440000", "songTitle": "Get Lucky" }, { "songId": "550e8400-e29b-41d4-a716-446655440111", "songTitle": "Loose yourself to dance" }, { "songId": "550e8400-e29b-41d4-a716-446655440222", "songTitle": "Gio sorgio by Moroder" } ] ================================================ FILE: samples/raml-tutorial-200/jukebox-include-album.schema ================================================ '{ "type": "object", "$schema": "http://json-schema.org/draft-03/schema", "id": "http://jsonschema.net", "required":false, "properties": { "albumId": { "type": "string", "required":true, "minLength": 36, "maxLength": 36 }, "albumName": { "type": "string", "required": true }, "year": { "type": "string", "required": false }, "iamgeURL": { "type": "string", "required": false }, "genreCode": { "type": "string", "required": true }, "artistId": { "type": "string", "required":true, "minLength": 36, "maxLength": 36 } } }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-albums.sample ================================================ '[ { "albumId": "183100e3-0e2b-4404-a716-66104d440550", "albumName": "Random Access Memories", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg", "artistId": "110e8300-e32b-41d4-a716-664400445500", "genre": { "countryCode": "ELE", "countryName": "Electronict" } }, { "albumId": "183100e3-0e2b-4404-3123-66111d4de520", "albumName": "OK Computer", "imageURL": "http://www.greenplastic.com/dev/wp-content/uploads/2010/12/ok-computer.jpg", "artistId": "11032be3-41d4-4455-a716-664400a71600", "genre": { "countryCode": "ALT", "countryName": "Alternative Rock" } }, { "albumId": "183100e3-cccc-4404-1111-63204d64coda", "albumName": "The Dark Side of the Moon", "imageURL": "http://upload.wikimedia.org/wikipedia/en/3/3b/Dark_Side_of_the_Moon.png", "artistId": "110e8300-e32b-41d4-a716-229932554400", "genre": { "countryCode": "PRO", "countryName": "Progressive Rock" } } ]' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-artist-albums.sample ================================================ '[ { "albumId": "183100e3-0e2b-4404-a716-66104d440550", "albumName": "Random Access Memories", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440551", "albumName": "TRON: Legacy R3CONF1GUR3D", "imageURL": "http://ecx.images-amazon.com/images/I/51Tvo-iArBL.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440552", "albumName": "TRON: Legacy", "imageURL": "http://upload.wikimedia.org/wikipedia/en/3/39/Tron_Legacy_Soundtrack.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440553", "albumName": "Alive", "imageURL": "http://upload.wikimedia.org/wikipedia/en/4/49/Daft_Punk_Alive_2007.JPG" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440554", "albumName": "Musique Vol. 1", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/ab/Musique_Vol._1_1993%E2%80%932005.png" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440555", "albumName": "Human After All", "imageURL": "http://upload.wikimedia.org/wikipedia/en/0/0d/Humanafterall.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440556", "albumName": "Daft Club", "imageURL": "http://upload.wikimedia.org/wikipedia/en/f/fc/Daftclub.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440557", "albumName": "Discovery", "imageURL": "http://ecx.images-amazon.com/images/I/71bsHTr6idL._SL1500_.jpg" } ]' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-artist-new.sample ================================================ '{ "artistName": "Daft Punk", "description": "French electronic music duo consisting of musicians Guy-Manuel de Homem-Christo and Thomas Bangalter", "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg" }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-artist-retrieve.sample ================================================ '{ "artistId": "110e8300-e32b-41d4-a716-664400445500", "artistName": "Daft Punk", "description": "French electronic music duo consisting of musicians Guy-Manuel de Homem-Christo and Thomas Bangalter", "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg", "nationality": { "countryCode": "FRA", "countryName": "France" }, "albums": [ { "albumId": "183100e3-0e2b-4404-a716-66104d440550", "albumName": "Random Access Memories", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440551", "albumName": "TRON: Legacy R3CONF1GUR3D", "imageURL": "http://ecx.images-amazon.com/images/I/51Tvo-iArBL.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440552", "albumName": "TRON: Legacy", "imageURL": "http://upload.wikimedia.org/wikipedia/en/3/39/Tron_Legacy_Soundtrack.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440553", "albumName": "Alive", "imageURL": "http://upload.wikimedia.org/wikipedia/en/4/49/Daft_Punk_Alive_2007.JPG" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440554", "albumName": "Musique Vol. 1", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/ab/Musique_Vol._1_1993%E2%80%932005.png" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440555", "albumName": "Human After All", "imageURL": "http://upload.wikimedia.org/wikipedia/en/0/0d/Humanafterall.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440556", "albumName": "Daft Club", "imageURL": "http://upload.wikimedia.org/wikipedia/en/f/fc/Daftclub.jpg" }, { "albumId": "183100e3-0e2b-4404-a716-66104d440557", "albumName": "Discovery", "imageURL": "http://ecx.images-amazon.com/images/I/71bsHTr6idL._SL1500_.jpg" }] }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-artist.schema ================================================ '{ "type": "object", "$schema": "http://json-schema.org/draft-03/schema", "id": "http://jsonschema.net", "required":false, "properties": { "artistName": { "type": "string", "required":true }, "description": { "type": "string", "required": false }, "imageURL": { "type": "string", "required": false } } }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-artists.sample ================================================ '[{ "artistId": "110e8300-e32b-41d4-a716-664400445500", "artistName": "Daft Punk", "description": "French electronic music duo consisting of musicians Guy-Manuel de Homem-Christo and Thomas Bangalter", "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg", "nationality": { "countryCode": "FRA", "countryName": "France" } }, { "artistId": "110e8300-e32b-41d4-a716-229932554400", "artistName": "Pink Floyd", "description": "English rock band that achieved international acclaim with their progressive and psychedelic music.", "imageURL": "http://www.billboard.com/files/styles/promo_650/public/stylus/1251869-pink-floyd-reunions-617-409.jpg", "nationality": { "countryCode": "ENG", "countryName": "England" } }, { "artistId": "11032be3-41d4-4455-a716-664400a71600", "artistName": "Radiohead", "description": " English rock band from Abingdon, Oxfordshire, formed in 1985", "imageURL": "http://www.wired.com/images_blogs/photos/uncategorized/2007/10/01/radiohead.jpg", "nationality": { "countryCode": "ENG", "countryName": "England" } }, ]' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-song-new.sample ================================================ '{ "songId": "550e8400-e29b-41d4-a716-446655440000", "songTitle": "Get Lucky", "albumId": "183100e3-0e2b-4404-a716-66104d440550" }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-song-retrieve.sample ================================================ '{ "songId": "550e8400-e29b-41d4-a716-446655440000", "songTitle": "Get Lucky", "duration": "6:07", "artist": { "artistId": "110e8300-e32b-41d4-a716-664400445500", "artistName": "Daft Punk", "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg" }, "album": { "albumId": "183100e3-0e2b-4404-a716-66104d440550", "albumName": "Random Access Memories", "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg" } }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-song.schema ================================================ '{ "type": "object", "$schema": "http://json-schema.org/draft-03/schema", "id": "http://jsonschema.net", "required": true, "properties": { "songId": { "type": "string", "required": true, "minLength": 36, "maxLength": 36 }, "songTitle": { "type": "string", "required": true }, "albumId": { "type": "string", "required": true, "minLength": 36, "maxLength": 36 } } }' ================================================ FILE: samples/raml-tutorial-200/jukebox-include-songs.sample ================================================ '[ { "songId": "550e8400-e29b-41d4-a716-446655440000", "songTitle": "Get Lucky" }, { "songId": "550e8400-e29b-41d4-a716-446655440111", "songTitle": "Loose yourself to dance" }, { "songId": "550e8400-e29b-41d4-a716-446655440222", "songTitle": "Gio sorgio by Morodera" } ]' ================================================ FILE: samples/sample_documentation.yaml ================================================ - title: Overview content: This is an example of a simple API for a "notes" service ================================================ FILE: samples/simple_example.raml ================================================ #%RAML 0.8 title: Notes Example API /jobs: displayName: Jobs post: description: Create a job /projects: displayName: Projects post: description: Create a project /resources: displayName: Resources type: searchableCollection: queryParamName: title fallbackParamName: digest_all_fields get: description: Get a resource is: - secured: tokenName: access_token paged: maxPages: 10 post: description: Post a resource /{resourceId}: get: description: Get a resource ID put: description: Put resource ID delete: description: Delete a resource ID /yet_another: get: description: Yet another uriParameters: communityDomain: displayName: Community Domain type: string communityPath: displayName: Community Path type: string pattern: ^[a-zA-Z0-9][-a-zA-Z0-9]*$ minLength: 1 baseUri: /lala protocols: [HTTP, HTTPS] traits: - secured: queryParameters: <>: description: A valid <> is required paged: queryParameters: numPages: description: The number of pages to return, not to exceed <> resourceTypes: - rttest: description: test - one: description: hi - auditableResource: post?: body: application/x-www-form-urlencoded: formParameters: createAuthority: description: | If the resource has a post method defined, expect a createAuthority property in its body delete?: body: multipart/form-data: formParameters: deleteAuthority: description: | If the resource has a delete method defined, expect a deleteAuthority property in its body - searchableCollection: get: queryParameters: <>: description: Return <> that have their <> matching the given value <>: description: If no values match the value given for <>, use <> instead securitySchemes: - oauth_2_0: description: | Dropbox supports OAuth 2.0 for authenticating all API requests. type: OAuth 2.0 describedBy: headers: Authorization: description: | Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter. type: string queryParameters: access_token: description: | Used to send a valid OAuth 2 access token. Do not use together with the "Authorization" header type: string responses: 401: description: | Bad or expired token. This can happen if the user or Dropbox revoked or expired an access token. To fix, you should re- authenticate the user. 403: description: | Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...). Unfortunately, re-authenticating the user won't help here. settings: authorizationUri: https://www.dropbox.com/1/oauth2/authorize accessTokenUri: https://api.dropbox.com/1/oauth2/token authorizationGrants: [ code, token ] - oauth_1_0: description: | OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred. type: OAuth 1.0 settings: requestTokenUri: https://api.dropbox.com/1/oauth/request_token authorizationUri: https://www.dropbox.com/1/oauth/authorize tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token - customHeader: description: | A custom ================================================ FILE: types.go ================================================ // Copyright 2014 DoAT. All rights reserved. // // Redistribution and use in source and binary forms, with or without modification, // are permitted provided that the following conditions are met: // // 1. Redistributions of source code must retain the above copyright notice, // this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright notice, // this list of conditions and the following disclaimer in the documentation and/or // other materials provided with the distribution. // // THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTIES WHATSOEVER. // ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, // THE IMPLIED WARRANTIES OF NON INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A // PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL DoAT OR CONTRIBUTORS // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, // EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // The views and conclusions contained in the software and documentation are those of // the authors and should not be interpreted as representing official policies, // either expressed or implied, of DoAT. // This package contains the parser, validator and types that implement the // RAML specification, as documented here: // http://raml.org/spec.html package raml // This file contains all of the RAML types. // TODO: We don't support !include of non-text files. RAML supports including // of many file types. // "Any" type, for our convenience type Any interface{} // For extra clarity type HTTPCode int // e.g. 200 type HTTPHeader string // e.g. Content-Length // The RAML Specification uses collections of named parameters for the // following properties: URI parameters, query string parameters, form // parameters, request bodies (depending on the media type), and request // and response headers. // // Some fields are pointers to distinguish Zero values and no values type NamedParameter struct { // NOTE: We currently do not support Named Parameters With Multiple Types. // TODO: Add support for Named Parameters With Multiple Types. Should be // done sort of like the DefinitionChoice type. // The name of the Parameter, as defined by the type containing it. Name string // TODO: Fill this during the post-processing phase // A friendly name used only for display or documentation purposes. // If displayName is not specified, it defaults to the property's key DisplayName string `yaml:"displayName"` // TODO: Auto-fill this // The intended use or meaning of the parameter Description string // The primitive type of the parameter's resolved value. Can be: // // Type Description // string - Value MUST be a string. // number - Value MUST be a number. Indicate floating point numbers as defined by YAML. // integer - Value MUST be an integer. Floating point numbers are not allowed. The integer type is a subset of the number type. // date - Value MUST be a string representation of a date as defined in RFC2616 Section 3.3 [RFC2616]. See Date Representations. // boolean - Value MUST be either the string "true" or "false" (without the quotes). // file - (Applicable only to Form properties) Value is a file. Client generators SHOULD use this type to handle file uploads correctly. Type string // TODO: Verify the enum options // If the enum attribute is defined, API clients and servers MUST verify // that a parameter's value matches a value in the enum array Enum []Any `yaml:",flow"` // The pattern attribute is a regular expression that a parameter of type // string MUST match. Regular expressions MUST follow the regular // expression specification from ECMA 262/Perl 5. (string only) Pattern *string // The minLength attribute specifies the parameter value's minimum number // of characters (string only) MinLength *int `yaml:"minLength"` // TODO: go-yaml doesn't raise an error when the minLength isn't an integer! // find out why and fix it. // The maxLength attribute specifies the parameter value's maximum number // of characters (string only) MaxLength *int `yaml:"maxLength"` // The minimum attribute specifies the parameter's minimum value. (numbers // only) Minimum *float64 // The maximum attribute specifies the parameter's maximum value. (numbers // only) Maximum *float64 // An example value for the property. This can be used, e.g., by // documentation generators to generate sample values for the property. Example string // The repeat attribute specifies that the parameter can be repeated, // i.e. the parameter can be used multiple times Repeat *bool // TODO: What does this mean? // Whether the parameter and its value MUST be present when a call is made. // In general, parameters are optional unless the required attribute is // included and its value set to 'true'. // For a URI parameter, its default value is 'true'. Required bool // The default value to use for the property if the property is omitted or // its value is not specified Default Any format Any `ramlFormat:"Named parameters must be mappings. Example: userId: {displayName: 'User ID', description: 'Used to identify the user.', type: 'integer', minimum: 1, example: 5}"` } // Headers used in Methods and other types type Header NamedParameter // All documentation of the API is of this format. type Documentation struct { Title string `yaml:"title"` Content string `yaml:"content"` } // Some method verbs expect the resource to be sent as a request body. // For example, to create a resource, the request must include the details of // the resource to create. // Resources CAN have alternate representations. For example, an API might // support both JSON and XML representations. type Body struct { mediaType string `yaml:"mediaType"` // TODO: Fill this during the post-processing phase // The structure of a request or response body MAY be further specified // by the schema property under the appropriate media type. // The schema key CANNOT be specified if a body's media type is // application/x-www-form-urlencoded or multipart/form-data. // All parsers of RAML MUST be able to interpret JSON Schema [JSON_SCHEMA] // and XML Schema [XML_SCHEMA]. // Alternatively, the value of the schema field MAY be the name of a schema // specified in the root-level schemas property Schema string `yaml:"schema"` // Brief description Description string `yaml:"description"` // Example attribute to generate example invocations Example string `yaml:"example"` // Web forms REQUIRE special encoding and custom declaration. // If the API's media type is either application/x-www-form-urlencoded or // multipart/form-data, the formParameters property MUST specify the // name-value pairs that the API is expecting. // The formParameters property is a map in which the key is the name of // the web form parameter, and the value is itself a map the specifies // the web form parameter's attributes FormParameters map[string]NamedParameter `yaml:"formParameters"` // TODO: This doesn't make sense in response bodies.. separate types for // request and response body? Headers map[HTTPHeader]Header `yaml:"headers"` } // Container of Body types, necessary because of technical reasons. type Bodies struct { // Instead of using a simple map[HTTPHeader]Body for the body // property of the Response and Method, we use the Bodies struct. Why? // Because some RAML APIs don't use the MIMEType part, instead relying // on the mediaType property in the APIDefinition. // So, you might see: // // responses: // 200: // body: // example: "some_example" : "123" // // and also: // // responses: // 200: // body: // application/json: // example: | // { // "some_example" : "123" // } // As in the Body type. DefaultSchema string `yaml:"schema"` // As in the Body type. DefaultDescription string `yaml:"description"` // As in the Body type. DefaultExample string `yaml:"example"` // As in the Body type. DefaultFormParameters map[string]NamedParameter `yaml:"formParameters"` // TODO: Is this ever used? I think I put it here by mistake. //Headers map[HTTPHeader]Header `yaml:"headers"` // Resources CAN have alternate representations. For example, an API // might support both JSON and XML representations. This is the map // between MIME-type and the body definition related to it. ForMIMEType map[string]Body `yaml:",regexp:.*"` // TODO: For APIs without a priori knowledge of the response types for // their responses, "*/*" MAY be used to indicate that responses that do // not matching other defined data types MUST be accepted. Processing // applications MUST match the most descriptive media type first if // "*/*" is used. } // Resource methods MAY have one or more responses. type Response struct { // HTTP status code of the response HTTPCode HTTPCode // TODO: Fill this during the post-processing phase // Clarifies why the response was emitted. Response descriptions are // particularly useful for describing error conditions. Description string // An API's methods may support custom header values in responses Headers map[HTTPHeader]Header `yaml:"headers"` // TODO: API's may include the the placeholder token {?} in a header name // to indicate that any number of headers that conform to the specified // format can be sent in responses. This is particularly useful for // APIs that allow HTTP headers that conform to some naming convention // to send arbitrary, custom data. // Each response MAY contain a body property. Responses that can return // more than one response code MAY therefore have multiple bodies defined. Bodies Bodies `yaml:"body"` } // A ResourceType/Trait/SecurityScheme choice contains the name of a // ResourceType/Trait/SecurityScheme as well as the parameters used to create // an instance of it. // Parameters MUST be of type string. type DefinitionParameters map[string]string type DefinitionChoice struct { Name string // The definitions of resource types and traits MAY contain parameters, // whose values MUST be specified when applying the resource type or trait, // UNLESS the parameter corresponds to a reserved parameter name, in which // case its value is provided by the processing application. // Same goes for security schemes. Parameters DefinitionParameters } // Unmarshal a node which MIGHT be a simple string or a // map[string]DefinitionParameters func (dc *DefinitionChoice) UnmarshalYAML(unmarshaler func(interface{}) error) error { simpleDefinition := new(string) parameterizedDefinition := make(map[string]DefinitionParameters) var err error // Unmarshal into a string if err = unmarshaler(simpleDefinition); err == nil { dc.Name = *simpleDefinition dc.Parameters = nil } else if err = unmarshaler(parameterizedDefinition); err == nil { // Didn't work? Now unmarshal into a map for choice, params := range parameterizedDefinition { dc.Name = choice dc.Parameters = params } } // Still didn't work? Panic return err } // A trait is a partial method definition that, like a method, can provide // method-level properties such as description, headers, query string // parameters, and responses. Methods that use one or more traits inherit // those traits' properties. type Trait struct { // TODO: Parameters MUST be indicated in resource type and trait definitions // by double angle brackets (double chevrons) enclosing the parameter name; // for example, "<>". // TODO: Auto-fill the methodName parameter // TODO: In trait definitions, there is one reserved parameter name, // methodName, in addition to the resourcePath and resourcePathName. The // processing application MUST set the value of the methodName parameter // to the inheriting method's name. The processing application MUST set // the values of the resourcePath and resourcePathName parameters the same // as in resource type definitions. // TODO: Parameter values MAY further be transformed by applying one of // the following functions: // * The !singularize function MUST act on the value of the parameter // by a locale-specific singularization of its original value. The only // locale supported by this version of RAML is United States English. // * The !pluralize function MUST act on the value of the parameter by a // locale-specific pluralization of its original value. The only locale // supported by this version of RAML is United States English. Name string // TODO: Fill this during the post-processing phase // The usage property of a resource type or trait is used to describe how // the resource type or trait should be used Usage string // Briefly describes what the method does to the resource Description string // As in Method. Bodies Bodies `yaml:"body"` // As in Method. Headers map[HTTPHeader]Header `yaml:"headers"` // As in Method. Responses map[HTTPCode]Response `yaml:"responses"` // As in Method. QueryParameters map[string]NamedParameter `yaml:"queryParameters"` // As in Method. Protocols []string `yaml:"protocols"` // When defining resource types and traits, it can be useful to capture // patterns that manifest several levels below the inheriting resource or // method, without requiring the creation of the intermediate levels. // For example, a resource type definition may describe a body parameter // that will be used if the API defines a post method for that resource, // but the processing application should not create the post method itself. // // This optional structure key indicates that the value of the property // should be applied if the property name itself (without the question // mark) is already defined (whether explicitly or implicitly) at the // corresponding level in that resource or method. OptionalBodies Bodies `yaml:"body?"` OptionalHeaders map[HTTPHeader]Header `yaml:"headers?"` OptionalResponses map[HTTPCode]Response `yaml:"responses?"` OptionalQueryParameters map[string]NamedParameter `yaml:"queryParameters?"` } // Method that is part of a ResourceType. DIfferentiated from Traits since it // doesn't contain Usage, optional fields etc. type ResourceTypeMethod struct { Name string // TODO: Fill this during the post-processing phase // Briefly describes what the method does to the resource Description string // As in Method. Bodies Bodies `yaml:"body"` // TODO: Check - how does the mediaType play play here? What it do? // As in Method. Headers map[HTTPHeader]Header `yaml:"headers"` // As in Method. Responses map[HTTPCode]Response `yaml:"responses"` // As in Method. QueryParameters map[string]NamedParameter `yaml:"queryParameters"` // As in Method. Protocols []string `yaml:"protocols"` } // Resource and method declarations are frequently repetitive. For example, if // an API requires OAuth authentication, the API definition must include the // access_token query string parameter (which is defined by the queryParameters // property) in all the API's resource method declarations. // // Moreover, there are many advantages to reusing patterns across multiple // resources and methods. For example, after defining a collection-type // resource's characteristics, that definition can be applied to multiple // resources. This use of patterns encouraging consistency and reduces // complexity for both servers and clients. // // A resource type is a partial resource definition that, like a resource, can // specify a description and methods and their properties. Resources that use // a resource type inherit its properties, such as its methods. type ResourceType struct { // TODO: Auto-fill the resourcePath and resourcePathName parameters // Remove mediaTypeExtension. // TODO: Parameters MUST be indicated in resource type and trait definitions // by double angle brackets (double chevrons) enclosing the parameter name; // for example, "<>". // TODO: In resource type definitions, there are two reserved parameter // names: resourcePath and resourcePathName. The processing application // MUST set the values of these reserved parameters to the inheriting // resource's path (for example, "/users") and the part of the path // following the rightmost "/" (for example, "users"), respectively. // Processing applications MUST also omit the value of any // mediaTypeExtension found in the resource's URI when setting // resourcePath and resourcePathName. // TODO: Parameter values MAY further be transformed by applying one of // the following functions: // * The !singularize function MUST act on the value of the parameter // by a locale-specific singularization of its original value. The only // locale supported by this version of RAML is United States English. // * The !pluralize function MUST act on the value of the parameter by a // locale-specific pluralization of its original value. The only locale // supported by this version of RAML is United States English. // Name of the resource type Name string // TODO: Fill this during the post-processing phase // The usage property of a resource type or trait is used to describe how // the resource type or trait should be used Usage string // Briefly describes what the resource type Description string // As in Resource. UriParameters map[string]NamedParameter `yaml:"uriParameters"` // As in Resource. BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"` // In a RESTful API, methods are operations that are performed on a // resource. A method MUST be one of the HTTP methods defined in the // HTTP version 1.1 specification [RFC2616] and its extension, // RFC5789 [RFC5789]. Get *ResourceTypeMethod `yaml:"get"` Head *ResourceTypeMethod `yaml:"head"` Post *ResourceTypeMethod `yaml:"post"` Put *ResourceTypeMethod `yaml:"put"` Delete *ResourceTypeMethod `yaml:"delete"` Patch *ResourceTypeMethod `yaml:"patch"` // When defining resource types and traits, it can be useful to capture // patterns that manifest several levels below the inheriting resource or // method, without requiring the creation of the intermediate levels. // For example, a resource type definition may describe a body parameter // that will be used if the API defines a post method for that resource, // but the processing application should not create the post method itself. // // This optional structure key indicates that the value of the property // should be applied if the property name itself (without the question // mark) is already defined (whether explicitly or implicitly) at the // corresponding level in that resource or method. OptionalUriParameters map[string]NamedParameter `yaml:"uriParameters?"` OptionalBaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters?"` OptionalGet *ResourceTypeMethod `yaml:"get?"` OptionalHead *ResourceTypeMethod `yaml:"head?"` OptionalPost *ResourceTypeMethod `yaml:"post?"` OptionalPut *ResourceTypeMethod `yaml:"put?"` OptionalDelete *ResourceTypeMethod `yaml:"delete?"` OptionalPatch *ResourceTypeMethod `yaml:"patch?"` } // A trait-like structure to a security scheme mechanism so as to extend // the mechanism, such as specifying response codes, HTTP headers or custom // documentation. type SecuritySchemeMethod struct { Bodies Bodies `yaml:"body"` Headers map[HTTPHeader]Header `yaml:"headers"` Responses map[HTTPCode]Response `yaml:"responses"` QueryParameters map[string]NamedParameter `yaml:"queryParameters"` } // Most REST APIs have one or more mechanisms to secure data access, identify // requests, and determine access level and data visibility. type SecurityScheme struct { Name string // TODO: Fill this during the post-processing phase // Briefly describes the security scheme Description string // The type attribute MAY be used to convey information about // authentication flows and mechanisms to processing applications // such as Documentation Generators and Client generators. Type string // TODO: Verify that it is of the values accepted: "OAuth 1.0", // "OAuth 2.0", "Basic Authentication", "Digest Authentication", // "x-{other}" // The describedBy attribute MAY be used to apply a trait-like structure // to a security scheme mechanism so as to extend the mechanism, such as // specifying response codes, HTTP headers or custom documentation. // This extension allows API designers to describe security schemes. // As a best practice, even for standard security schemes, API designers // SHOULD describe the security schemes' required artifacts, such as // headers, URI parameters, and so on. // Including the security schemes' description completes an API's documentation. DescribedBy SecuritySchemeMethod // The settings attribute MAY be used to provide security schema-specific // information. Depending on the value of the type parameter, its attributes // can vary. Settings map[string]Any // TODO: Verify OAuth 1.0, 2.0 settings // TODO: Add to documentaiotn // If the scheme's type is x-other, API designers can use the properties // in this mapping to provide extra information to clients that understand // the x-other type. Other map[string]string } // Methods are operations that are performed on a resource type Method struct { Name string // TODO: Fill this during the post-processing phase // Briefly describes what the method does to the resource Description string // Applying a securityScheme definition to a method overrides whichever // securityScheme has been defined at the root level. To indicate that // the method is protected using a specific security scheme, the method // MUST be defined by using the securedBy attribute // Custom parameters can be provided to the security scheme. SecuredBy []DefinitionChoice `yaml:"securedBy"` // TODO: To indicate that the method may be called without applying any // securityScheme, the method may be annotated with the null securityScheme. // The method's non-standard HTTP headers. The headers property is a map // in which the key is the name of the header, and the value is itself a // map specifying the header attributes. Headers map[HTTPHeader]Header `yaml:"headers"` // TODO: Examples for headers are REQUIRED. // TODO: If the header name contains the placeholder token {*}, processing // applications MUST allow requests to send any number of headers that // conform to the format specified, with {*} replaced by 0 or more valid // header characters, and offer a way for implementations to add an // arbitrary number of such headers. This is particularly useful for APIs // that allow HTTP headers that conform to custom naming conventions to // send arbitrary, custom data. // A RESTful API method can be reached HTTP, HTTPS, or both. // A method can override an API's protocols value for that single method // by setting a different value for the fields. Protocols []string `yaml:"protocols"` // The queryParameters property is a map in which the key is the query // parameter's name, and the value is itself a map specifying the query // parameter's attributes QueryParameters map[string]NamedParameter `yaml:"queryParameters"` // Some method verbs expect the resource to be sent as a request body. // A method's body is defined in the body property as a hashmap, in which // the key MUST be a valid media type. Bodies Bodies `yaml:"body"` // TODO: Check - how does the mediaType play play here? What it do? // Resource methods MAY have one or more responses. Responses MAY be // described using the description property, and MAY include example // attributes or schema properties. // Responses MUST be a map of one or more HTTP status codes, where each // status code itself is a map that describes that status code. Responses map[HTTPCode]Response `yaml:"responses"` // Methods may specify one or more traits from which they inherit using the // is property Is []DefinitionChoice `yaml:"is"` // TODO: Add support for inline traits? } // A resource is the conceptual mapping to an entity or set of entities. type Resource struct { // Resources are identified by their relative URI, which MUST begin with // a slash (/). URI string // TODO: Fill this during the post-processing phase // A resource defined as a child property of another resource is called a // nested resource, and its property's key is its URI relative to its // parent resource's URI. If this is not nil, then this resource is a // child resource. Parent *Resource // TODO: Fill this during the post-processing phase // A friendly name to the resource DisplayName string // Briefly describes the resource Description string // A securityScheme may also be applied to a resource by using the // securedBy key, which is equivalent to applying the securityScheme to // all methods of this Resource. // Custom parameters can be provided to the security scheme. SecuredBy []DefinitionChoice `yaml:"securedBy"` // TODO: To indicate that the method may be called without applying any // securityScheme, the method may be annotated with the null securityScheme. // A resource or a method can override a base URI template's values. // This is useful to restrict or change the default or parameter selection // in the base URI. The baseUriParameters property MAY be used to override // any or all parameters defined at the root level baseUriParameters // property, as well as base URI parameters not specified at the root level. // In a resource structure of resources and nested resources with their // methods, the most specific baseUriParameter fully overrides any // baseUriParameter definition made before BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"` // Template URIs containing URI parameters can be used to define a // resource's relative URI when it contains variable elements. // The values matched by URI parameters cannot contain slash (/) characters UriParameters map[string]NamedParameter `yaml:"uriParameters"` // TODO: If a URI parameter in a resource's relative URI is not explicitly // described in a uriParameters property for that resource, it MUST still // be treated as a URI parameter with defaults as specified in the Named // Parameters section of this specification. Its type is "string", it is // required, and its displayName is its name (i.e. without the surrounding // curly brackets [{] and [}]). In the example below, the top-level // resource has two URI parameters, "folderId" and "fileId // TOOD: A special uriParameter, mediaTypeExtension, is a reserved // parameter. It may be specified explicitly in a uriParameters property // or not specified explicitly, but its meaning is reserved: it is used // by a client to specify that the body of the request or response be of // the associated media type. By convention, a value of .json is // equivalent to an Accept header of application/json and .xml is // equivalent to an Accept header of text/xml. // Resources may specify the resource type from which they inherit using // the type property. The resource type may be defined inline as the value // of the type property (directly or via an !include), or the value of // the type property may be the name of a resource type defined within // the root-level resourceTypes property. // NOTE: inline not currently supported. Type *DefinitionChoice `yaml:"type"` // TODO: Add support for inline ResourceTypes // A resource may use the is property to apply the list of traits to all // its methods. Is []DefinitionChoice `yaml:"is"` // TODO: Add support for inline traits? // In a RESTful API, methods are operations that are performed on a // resource. A method MUST be one of the HTTP methods defined in the // HTTP version 1.1 specification [RFC2616] and its extension, // RFC5789 [RFC5789]. Get *Method `yaml:"get"` Head *Method `yaml:"head"` Post *Method `yaml:"post"` Put *Method `yaml:"put"` Delete *Method `yaml:"delete"` Patch *Method `yaml:"patch"` // A resource defined as a child property of another resource is called a // nested resource, and its property's key is its URI relative to its // parent resource's URI. Nested map[string]*Resource `yaml:",regexp:/.*"` } // TODO: Resource.GetBaseURIParameter --> includeds APIDefinition BURIParams.. // TODO: Resource.GetAbsoluteURI // The API Definition describes the basic information of an API, such as its // title and base URI, and describes how to define common schema references. type APIDefinition struct { // RAML 0.8 RAMLVersion string `yaml:"raml_version"` // The title property is a short plain text description of the RESTful API. // The title property's value SHOULD be suitable for use as a title for the // contained user documentation Title string `yaml:"title"` // If RAML API definition is targeted to a specific API version, it should // be noted here Version string `yaml:"version"` // A RESTful API's resources are defined relative to the API's base URI. // If the baseUri value is a Level 1 Template URI, the following reserved // base URI parameters are available for replacement: // // version - The content of the version field. BaseUri string // TODO: If a URI template variable in the base URI is not explicitly // described in a baseUriParameters property, and is not specified in a // resource-level baseUriParameters property, it MUST still be treated as // a base URI parameter with defaults as specified in the Named Parameters // section of this specification. Its type is "string", it is required, // and its displayName is its name (i.e. without the surrounding curly // brackets [{] and [}]). // A resource or a method can override a base URI template's values. // This is useful to restrict or change the default or parameter selection // in the base URI. The baseUriParameters property MAY be used to override // any or all parameters defined at the root level baseUriParameters // property, as well as base URI parameters not specified at the root level. // In a resource structure of resources and nested resources with their // methods, the most specific baseUriParameter fully overrides any // baseUriParameter definition made before BaseUriParameters map[string]NamedParameter `yaml:"baseUriParameters"` // TODO: Generate these also from the baseUri // Level 1 URI custom parameters, which are useful in a variety of scenario. // URI parameters can be further defined by using the uriParameters // property. The use of uriParameters is OPTIONAL. The uriParameters // property MUST be a map in which each key MUST be the name of the URI // parameter as defined in the baseUri property. The uriParameters CANNOT // contain a key named version because it is a reserved URI parameter name. UriParameters map[string]NamedParameter `yaml:"uriParameters"` // A RESTful API can be reached HTTP, HTTPS, or both Protocols []string `yaml:"protocols"` // The media types returned by API responses, and expected from API // requests that accept a body, MAY be defaulted by specifying the // mediaType property. // The property's value MAY be a single string with a valid media type: // // One of the following YAML media types: // * text/yaml // * text/x-yaml // * application/yaml // * application/x-yaml* // // Any type from the list of IANA MIME Media Types, // http://www.iana.org/assignments/media-types // A custom type that conforms to the regular expression: // * "application\/[A-Za-z.-0-1]*+?(json|xml)" MediaType string `yaml:"mediaType"` // The schemas property specifies collections of schemas that could be // used anywhere in the API definition. // The value of the schemas property is an array of maps; in each map, // the keys are the schema name, and the values are schema definitions: // []map[SchemaName]SchemaString Schemas []map[string]string // TODO: Flatten the arrays of maps here. // The securitySchemes property MUST be used to specify an API's security // mechanisms, including the required settings and the authentication // methods that the API supports. // []map[SchemeName]SecurityScheme SecuritySchemes []map[string]SecurityScheme `yaml:"securitySchemes"` // TODO: Flatten the arrays of maps here. // To apply a securityScheme definition to every method in an API, the // API MAY be defined using the securedBy attribute. This specifies that // all methods in the API are protected using that security scheme. // Custom parameters can be provided to the security scheme. SecuredBy []DefinitionChoice `yaml:"securedBy"` // The API definition can include a variety of documents that serve as a // user guides and reference documentation for the API. Such documents can // clarify how the API works or provide business context. // All the sections are in the order in which the documentation is declared. Documentation []Documentation `yaml:"documentation"` // To apply a trait definition to a method, so that the method inherits the // trait's characteristics, the method MUST be defined by using the is // attribute. The value of the is attribute MUST be an array of any number // of elements, each of which MUST be a) one or more trait keys (names) // included in the traits declaration, or b) one or more trait definition // maps. // []map[TraitName]Trait Traits []map[string]Trait `yaml:"traits"` // TODO: Flatten the arrays of maps here. // The resourceTypes and traits properties are declared at the API // definition's root level with the resourceTypes and traits property keys, // respectively. The value of each of these properties is an array of maps; // in each map, the keys are resourceType or trait names, and the values // are resourceType or trait definitions, respectively. // []map[ResourceTypeName]ResourceType ResourceTypes []map[string]ResourceType `yaml:"resourceTypes"` // TODO: Flatten the arrays of maps here. // Resources are identified by their relative URI, which MUST begin with a // slash (/). A resource defined as a root-level property is called a // top-level resource. Its property's key is the resource's URI relative // to the baseUri. A resource defined as a child property of another // resource is called a nested resource, and its property's key is its // URI relative to its parent resource's URI. Resources map[string]Resource `yaml:",regexp:/.*"` } // This function receives a path, splits it and traverses the resource // tree to find the appropriate resource func (r *APIDefinition) GetResource(path string) *Resource { return nil } ================================================ FILE: validator.go ================================================ // Copyright 2014 DoAT. All rights reserved. // // Redistribution and use in source and binary forms, with or without modification, // are permitted provided that the following conditions are met: // // 1. Redistributions of source code must retain the above copyright notice, // this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright notice, // this list of conditions and the following disclaimer in the documentation and/or // other materials provided with the distribution. // // THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTIES WHATSOEVER. // ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, // THE IMPLIED WARRANTIES OF NON INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A // PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL DoAT OR CONTRIBUTORS // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, // EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // The views and conclusions contained in the software and documentation are those of // the authors and should not be interpreted as representing official policies, // either expressed or implied, of DoAT. package raml // This file contains all of the RAML schema validator related code. // TODO: Inspirations: // https://www.npmjs.com/package/raml-validate // https://github.com/go-validator/validator // https://github.com/asaskevich/govalidator // And of course: // https://github.com/raml-org/raml-java-parser/tree/master/src/main/java/org/raml/parser/rule