Showing preview only (1,018K chars total). Download the full file or copy to clipboard to get everything.
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 <diamant.alon@gmail.com> [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
================================================
[](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:
<<tokenName>>:
description: A valid <<tokenName>> is required
paged:
queryParameters:
numPages:
description: The number of pages to return, not to exceed <<maxPages>>
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:
<<queryParamName>>:
description: Return <<resourcePathName>> that have their <<queryParamName>> matching the given value
<<fallbackParamName>>:
description: If no values match the value given for <<queryParamName>>, use <<fallbackParamName>> 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: <<someParameterName>>
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.
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
SYMBOL INDEX (30 symbols across 4 files)
FILE: errors.go
type RamlError (line 41) | type RamlError struct
method Error (line 45) | func (e *RamlError) Error() string {
function populateRAMLError (line 52) | func populateRAMLError(ramlError *RamlError,
function convertYAMLError (line 65) | func convertYAMLError(yamlError string) string {
FILE: parser.go
function ParseFile (line 48) | func ParseFile(filePath string) (*APIDefinition, error) {
function readFileContents (line 124) | func readFileContents(workingDirectory string, fileName string) ([]byte,...
function preProcess (line 145) | func preProcess(originalContents io.Reader, workingDirectory string) ([]...
FILE: raml_test.go
function TestFailedParsing (line 45) | func TestFailedParsing(t *testing.T) {
function TestParsing (line 63) | func TestParsing(t *testing.T) {
FILE: types.go
type Any (line 39) | type Any interface
type HTTPCode (line 42) | type HTTPCode
type HTTPHeader (line 43) | type HTTPHeader
type NamedParameter (line 51) | type NamedParameter struct
type Header (line 129) | type Header
type Documentation (line 132) | type Documentation struct
type Body (line 142) | type Body struct
type Bodies (line 177) | type Bodies struct
type Response (line 229) | type Response struct
type DefinitionParameters (line 257) | type DefinitionParameters
type DefinitionChoice (line 258) | type DefinitionChoice struct
method UnmarshalYAML (line 271) | func (dc *DefinitionChoice) UnmarshalYAML(unmarshaler func(interface{}...
type Trait (line 299) | type Trait struct
type ResourceTypeMethod (line 367) | type ResourceTypeMethod struct
type ResourceType (line 405) | type ResourceType struct
type SecuritySchemeMethod (line 484) | type SecuritySchemeMethod struct
type SecurityScheme (line 493) | type SecurityScheme struct
type Method (line 532) | type Method struct
type Resource (line 591) | type Resource struct
type APIDefinition (line 686) | type APIDefinition struct
method GetResource (line 810) | func (r *APIDefinition) GetResource(path string) *Resource {
Condensed preview — 34 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (1,084K chars).
[
{
"path": ".gitignore",
"chars": 266,
"preview": "# Compiled Object files, Static and Dynamic libs (Shared Objects)\n*.o\n*.a\n*.so\n\n# Folders\n_obj\n_test\n\n# Architecture spe"
},
{
"path": ".travis.yml",
"chars": 72,
"preview": "language: go\ngo: \n - 1.6.3\n - 1.7.1\n - tip\n\nscript:\n - go test -v ./...\n"
},
{
"path": "CONTRIBUTORS",
"chars": 196,
"preview": "go-raml Contributor List (ordered by date):\n\nAlon Diamant <diamant.alon@gmail.com> [https://github.com/advance512]\nDvir "
},
{
"path": "LICENSE",
"chars": 1485,
"preview": "Copyright 2014 DoAT. All rights reserved.\n\nRedistribution and use in source and binary forms, with or without modificati"
},
{
"path": "README.md",
"chars": 2490,
"preview": "[](https://travis-ci.org/go-raml/raml)\n\nLooking for act"
},
{
"path": "errors.go",
"chars": 6001,
"preview": "// Copyright 2014 DoAT. All rights reserved.\n//\n// Redistribution and use in source and binary forms, with or without mo"
},
{
"path": "parser.go",
"chars": 7046,
"preview": "// Copyright 2014 DoAT. All rights reserved.\n//\n// Redistribution and use in source and binary forms, with or without mo"
},
{
"path": "raml_test.go",
"chars": 3141,
"preview": "// Copyright 2014 DoAT. All rights reserved.\n//\n// Redistribution and use in source and binary forms, with or without mo"
},
{
"path": "samples/bad_raml.raml",
"chars": 4172,
"preview": "#%RAML 0.8\ntitle: Notes Example API\n/jobs:\n displayName: Jobs\n post:\n description: Create a job\n/projects:\n disp"
},
{
"path": "samples/congo/api.raml",
"chars": 5460,
"preview": "#%RAML 0.8\ntitle: Congo API For Drone Deliveries\nmediaType: application/json\n/deliveries:\n get:\n description: Get a "
},
{
"path": "samples/example.raml",
"chars": 5790,
"preview": "#%RAML 0.8\n---\ntitle: Example API\nbaseUri: http://example.com\nsecuritySchemes:\n - basic:\n type: Basic Authenticati"
},
{
"path": "samples/github/github-api-v3.raml",
"chars": 909744,
"preview": "#%RAML 0.8\n---\ntitle: GitHub API\nversion: v3\nbaseUri: https://api.github.com/\nsecuritySchemes:\n - oauth_2_0:\n desc"
},
{
"path": "samples/notes/api.raml",
"chars": 2681,
"preview": "#%RAML 0.8\ntitle: Notes Example API\nversion: v2\nmediaType: application/json\ndocumentation:\n - title: Overview\n conte"
},
{
"path": "samples/other_example.raml",
"chars": 5413,
"preview": "#%RAML 0.8\ntitle: Notes Example API\nmediaType: application/json\ndocumentation:\n - title: Overview\n content: This is "
},
{
"path": "samples/raml-tutorial-200/README.md",
"chars": 73,
"preview": "raml-tutorial-200\n=================\n\nStep by step 200 raml tutorial code\n"
},
{
"path": "samples/raml-tutorial-200/jukebox-api.raml",
"chars": 6292,
"preview": "#%RAML 0.8\n---\ntitle: Jukebox API\nbaseUri: http://jukebox.api.com\nversion: v1\n\nschemas:\n - song: !include jukebox-includ"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-album-new.sample",
"chars": 283,
"preview": "'{\n \"albumId\": \"183100e3-0e2b-4404-a716-66104d440550\",\n \"albumName\": \"Random Access Memories\",\n \"year\": \"2013\",\n \"im"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-album-retrieve.sample",
"chars": 833,
"preview": "'{\n \"albumId\": \"183100e3-0e2b-4404-a716-66104d440550\",\n \"albumName\": \"Random Access Memories\",\n \"year\": \"2013\",\n \"ge"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-album-songs.sample",
"chars": 305,
"preview": "[\n {\n \"songId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"songTitle\": \"Get Lucky\"\n },\n {\n \"songId\": \"550e840"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-album.schema",
"chars": 676,
"preview": "'{\n \"type\": \"object\",\n \"$schema\": \"http://json-schema.org/draft-03/schema\",\n \"id\": \"http://jsonschema.net\",\n \"requir"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-albums.sample",
"chars": 1025,
"preview": "'[\n {\n \"albumId\": \"183100e3-0e2b-4404-a716-66104d440550\",\n \"albumName\": \"Random Access Memories\",\n \"imageURL\":"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-artist-albums.sample",
"chars": 1480,
"preview": "'[\n {\n \"albumId\": \"183100e3-0e2b-4404-a716-66104d440550\",\n \"albumName\": \"Random Access Memories\",\n \"imageURL\":"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-artist-new.sample",
"chars": 250,
"preview": "'{\n \"artistName\": \"Daft Punk\",\n \"description\": \"French electronic music duo consisting of musicians Guy-Manuel de Home"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-artist-retrieve.sample",
"chars": 1872,
"preview": "'{\n \"artistId\": \"110e8300-e32b-41d4-a716-664400445500\",\n \"artistName\": \"Daft Punk\",\n \"description\": \"French electroni"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-artist.schema",
"chars": 377,
"preview": "'{\n \"type\": \"object\",\n \"$schema\": \"http://json-schema.org/draft-03/schema\",\n \"id\": \"http://jsonschema.net\",\n \"requir"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-artists.sample",
"chars": 1137,
"preview": "'[{\n \"artistId\": \"110e8300-e32b-41d4-a716-664400445500\",\n \"artistName\": \"Daft Punk\",\n \"description\": \"French electron"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-song-new.sample",
"chars": 138,
"preview": "'{\n \"songId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"songTitle\": \"Get Lucky\",\n \"albumId\": \"183100e3-0e2b-4404-a716"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-song-retrieve.sample",
"chars": 516,
"preview": "'{\n \"songId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"songTitle\": \"Get Lucky\",\n \"duration\": \"6:07\",\n \"artist\": {\n "
},
{
"path": "samples/raml-tutorial-200/jukebox-include-song.schema",
"chars": 461,
"preview": "'{\n \"type\": \"object\",\n \"$schema\": \"http://json-schema.org/draft-03/schema\",\n \"id\": \"http://jsonschema.net\",\n \"requir"
},
{
"path": "samples/raml-tutorial-200/jukebox-include-songs.sample",
"chars": 308,
"preview": "'[\n {\n \"songId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"songTitle\": \"Get Lucky\"\n },\n {\n \"songId\": \"550e84"
},
{
"path": "samples/sample_documentation.yaml",
"chars": 86,
"preview": "- title: Overview\n content: This is an example of a simple API for a \"notes\" service\n"
},
{
"path": "samples/simple_example.raml",
"chars": 4164,
"preview": "#%RAML 0.8\ntitle: Notes Example API\n/jobs:\n displayName: Jobs\n post:\n description: Create a job\n/projects:\n displa"
},
{
"path": "types.go",
"chars": 35340,
"preview": "// Copyright 2014 DoAT. All rights reserved.\n//\n// Redistribution and use in source and binary forms, with or without mo"
},
{
"path": "validator.go",
"chars": 1926,
"preview": "// Copyright 2014 DoAT. All rights reserved.\n//\n// Redistribution and use in source and binary forms, with or without mo"
}
]
About this extraction
This page contains the full source code of the go-raml/raml GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 34 files (987.8 KB), approximately 163.0k tokens, and a symbol index with 30 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.