lib/trav3.rb in trav3-0.2.3 vs lib/trav3.rb in trav3-0.2.4

- old
+ new

@@ -4,13 +4,11 @@ require 'trav3/version' require 'trav3/pagination' require 'trav3/options' require 'trav3/headers' require 'trav3/result' -require 'trav3/delete' -require 'trav3/post' -require 'trav3/get' +require 'trav3/rest' # Trav3 project namespace module Trav3 API_ROOT = 'https://api.travis-ci.org' @@ -77,10 +75,71 @@ def h(**args) (@headers ||= Headers.new).build(**args) self end + # Please Note that the naming of this endpoint may be changed. Our naming convention for this information is in flux. If you have suggestions for how this information should be presented please leave us feedback by commenting in this issue here or emailing support support@travis-ci.com. + # + # A list of all the builds in an "active" state, either created or started. + # + # ## Attributes + # + # Name Type Description + # builds Builds The active builds. + # + # ## Actions + # + # **For Owner** + # + # Returns a list of "active" builds for the owner. + # + # GET <code>/owner/{owner.login}/active</code> + # + # Template Variable Type Description + # owner.login String User or organization login set on GitHub. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /owner/danielpclark/active + # + # GET <code>/owner/{user.login}/active</code> + # + # Template Variable Type Description + # user.login String Login set on Github. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /owner/danielpclark/active + # + # GET <code>/owner/{organization.login}/active</code> + # + # Template Variable Type Description + # organization.login String Login set on GitHub. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /owner/travis-ci/active + # + # GET <code>/owner/github_id/{owner.github_id}/active</code> + # + # Template Variable Type Description + # owner.github_id Integer User or organization id set on GitHub. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /owner/github_id/639823/active + # + # @param owner [String] username, organization name, or github id + # @return [Success, RequestError] + def active(owner = username) + if number? owner + get("#{without_repo}/owner/github_id/#{owner}/active") + else + get("#{without_repo}/owner/#{owner}/active") + end + end + # The branch of a GitHub repository. Useful for obtaining information about the last build on a given branch. # # **If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters.** # # ## Attributes @@ -120,21 +179,21 @@ # repository.id Integer Value uniquely identifying the repository. # branch.name String Name of the git branch. # Query Parameter Type Description # include [String] List of attributes to eager load. # - # Example:GET /repo/891/branch/master + # Example: GET /repo/891/branch/master # # GET <code>/repo/{repository.slug}/branch/{branch.name}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # branch.name String Name of the git branch. # Query Parameter Type Description # include [String] List of attributes to eager load. # - # Example:GET /repo/rails%2Frails/branch/master + # Example: GET /repo/rails%2Frails/branch/master # # @param name [String] the branch name for the current repository # @return [Success, RequestError] def branch(name) get("#{with_repo}/branch/#{name}") @@ -177,11 +236,11 @@ # include [String] List of attributes to eager load. # limit Integer How many branches to include in the response. Used for pagination. # offset Integer How many branches to skip before the first entry in the response. Used for pagination. # sort_by [String] Attributes to sort branches by. Used for pagination. # - # Example:GET /repo/891/branches?limit=5&exists_on_github=true + # Example: GET /repo/891/branches?limit=5&exists_on_github=true # # **Sortable by:** <code>name</code>, <code>last_build</code>, <code>exists_on_github</code>, <code>default_branch</code>, append <code>:desc</code> to any attribute to reverse order. # The default value is <code>default_branch</code>,<code>exists_on_github</code>,<code>last_build:desc</code>. # # GET <code>/repo/{repository.slug}/branches</code> @@ -194,11 +253,11 @@ # include [String] List of attributes to eager load. # limit Integer How many branches to include in the response. Used for pagination. # offset Integer How many branches to skip before the first entry in the response. Used for pagination. # sort_by [String] Attributes to sort branches by. Used for pagination. # - # Example:GET /repo/rails%2Frails/branches?limit=5&exists_on_github=true + # Example: GET /repo/rails%2Frails/branches?limit=5&exists_on_github=true # # **Sortable by:** <code>name</code>, <code>last_build</code>, <code>exists_on_github</code>, <code>default_branch</code>, append <code>:desc</code> to any attribute to reverse order. # The default value is <code>default_branch</code>,<code>exists_on_github</code>,<code>last_build:desc</code>. # # @return [Success, RequestError] @@ -700,11 +759,11 @@ # # **Lint** # # POST <code>/lint</code> # - # Example:POST /lint + # Example: POST /lint # # @param yaml_content [String] the contents for the file `.travis.yml` # @return [Success, RequestError] def lint(yaml_content) validate_string yaml_content @@ -768,11 +827,11 @@ # # Query Parameter Type Description # include [String] List of attributes to eager load. # log.token Unknown Documentation missing. # - # Example:GET /job/86601347/log.txt + # Example: GET /job/86601347/log.txt # # **Delete** # # This removes the contents of a log. It gets replace with the message: Log removed by XXX at 2017-02-13 16:00:00 UTC. # @@ -846,11 +905,11 @@ # Template Variable Type Description # organization.id Integer Value uniquely identifying the organization. # Query Parameter Type Description # include [String] List of attributes to eager load. # - # Example:GET /org/87 + # Example: GET /org/87 # # @param org_id [String, Integer] the organization id # @raise [TypeError] if given organization id is not a number # @return [Success, RequestError] def organization(org_id) @@ -895,11 +954,11 @@ # offset Integer How many organizations to skip before the first entry in the response. Used for pagination. # organization.role Unknown Documentation missing. # role Unknown Alias for organization.role. # sort_by [String] Attributes to sort organizations by. Used for pagination. # - # Example:GET /orgs?limit=5 + # Example: GET /orgs?limit=5 # # **Sortable by:** <code>id</code>, <code>login</code>, <code>name</code>, <code>github_id</code>, append <code>:desc</code> to any attribute to reverse order. # # @return [Success, RequestError] def organizations @@ -978,11 +1037,11 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/github_id/639823 # - # @param owner [String] username or github ID + # @param owner [String] username or github id # @return [Success, RequestError] def owner(owner = username) if number? owner get("#{without_repo}/owner/github_id/#{owner}") else @@ -1124,11 +1183,11 @@ # # Example: GET /repos?limit=5&sort_by=active,name # # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # - # @param owner [String] username or github ID + # @param owner [String] username or github id # @return [Success, RequestError] def repositories(owner = username) if number? owner get("#{without_repo}/owner/github_id/#{owner}/repos#{opts}") else @@ -1316,21 +1375,165 @@ # Template Variable Type Description # build.id Integer Value uniquely identifying the build. # Query Parameter Type Description # include [String] List of attributes to eager load. # - # Example:GET /build/86601346/stages + # Example: GET /build/86601346/stages # # @param build_id [String, Integer] build id # @raise [TypeError] if given build id is not a number # @return [Success, RequestError] def stages(build_id) validate_number build_id get("#{without_repo}/build/#{build_id}/stages") end + # An individual repository setting. These are settings on a repository that can be adjusted by the user. There are currently five different kinds of settings a user can modify: + # + # * `builds_only_with_travis_yml` (boolean) + # * `build_pushes` (boolean) + # * `build_pull_requests` (boolean) + # * `maximum_number_of_builds` (integer) + # * `auto_cancel_pushes` (boolean) + # * `auto_cancel_pull_requests` (boolean) + # + # If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters. + # + # ## Attributes + # + # **Standard Representation** + # + # Included when the resource is the main response of a request, or is {https://developer.travis-ci.com/eager-loading eager loaded}. + # + # Name Type Description + # name String The setting's name. + # value Boolean or integer The setting's value. + # + # **Minimal Representation** + # + # Included when the resource is returned as part of another resource. + # + # Name Type Description + # name String The setting's name. + # value Boolean or integer The setting's value. + # + # ## Actions + # + # **Find** + # + # This returns a single setting. It is possible to use the repository id or slug in the request. + # + # GET <code>/repo/{repository.id}/setting/{setting.name}</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # setting.name String The setting's name. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # GET <code>/repo/{repository.slug}/setting/{setting.name}</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # setting.name String The setting's name. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # **Update** + # + # This updates a single setting. It is possible to use the repository id or slug in the request. + # + # Use namespaced params in the request body to pass the new setting: + # + # ```bash + # curl -X PATCH \ + # -H "Content-Type: application/json" \ + # -H "Travis-API-Version: 3" \ + # -H "Authorization: token xxxxxxxxxxxx" \ + # -d '{ "setting.value": true }' \ + # https://api.travis-ci.com/repo/1234/setting/{setting.name} + # ``` + # + # PATCH <code>/repo/{repository.id}/setting/{setting.name}</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # setting.name String The setting's name. + # Accepted Parameter Type Description + # setting.value Boolean or integer The setting's value. + # + # PATCH <code>/repo/{repository.slug}/setting/{setting.name}</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # setting.name String The setting's name. + # Accepted Parameter Type Description + # setting.value Boolean or integer The setting's value. + # + # @param name [String] the setting name for the current repository + # @param value [String] optional argument for setting a value for the setting name + # @return [Success, RequestError] + def setting(name, value = nil) + return get("#{with_repo}/setting/#{name}") if value.nil? + + patch("#{with_repo}/setting/#{name}", 'setting.value' => value) + end + + # A list of user settings. These are settings on a repository that can be adjusted by the user. There are currently six different kinds of user settings: + # + # * `builds_only_with_travis_yml` (boolean) + # * `build_pushes` (boolean) + # * `build_pull_requests` (boolean) + # * `maximum_number_of_builds` (integer) + # * `auto_cancel_pushes` (boolean) + # * `auto_cancel_pull_requests` (boolean) + # + # If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters. + # + # ## Attributes + # + # Name Type Description + # settings [Setting] List of settings. + # + # **Collection Items** + # + # Each entry in the settings array has the following attributes: + # + # Name Type Description + # name String The setting's name. + # value Boolean or integer The setting's value. + # + # ## Actions + # + # **For Repository** + # + # This returns a list of the settings for that repository. It is possible to use the repository id or slug in the request. + # + # GET <code>/repo/{repository.id}/settings</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /repo/891/settings + # + # GET <code>/repo/{repository.slug}/settings</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /repo/rails%2Frails/settings + # + # @return [Success, RequestError] + def settings + get("#{with_repo}/settings") + end + # An individual user. # # ## Attributes # # **Minimal Representation** @@ -1374,33 +1577,33 @@ # Template Variable Type Description # user.id Integer Value uniquely identifying the user. # Query Parameter Type Description # include [String] List of attributes to eager load. # - # Example:GET /user/119240 + # Example: GET /user/119240 # # **Sync** # # This triggers a sync on a user's account with their GitHub account. # # POST <code>/user/{user.id}/sync</code> # # Template Variable Type Description # user.id Integer Value uniquely identifying the user. # - # Example:POST /user/119240/sync + # Example: POST /user/119240/sync # # **Current** # # This will return information about the current user. # # GET <code>/user</code> # # Query Parameter Type Description # include [String] List of attributes to eager load. # - # Example:GET /user + # Example: GET /user # # @note sync feature may not be permitted # @note POST requests require an authorization token set in the headers. See: {h} # # @param user_id [String, Integer] optional user id @@ -1420,15 +1623,15 @@ end private # @private def delete(url) - Trav3::DELETE.call(self, url) + Trav3::REST.delete(self, url) end def get(url, raw_reply = false) - Trav3::GET.call(self, url, raw_reply) + Trav3::REST.get(self, url, raw_reply) end def initial_defaults defaults(limit: 25) h('Content-Type': 'application/json') @@ -1442,11 +1645,15 @@ def opts @options end + def patch(url, data) + Trav3::REST.patch(self, url, data) + end + def post(url, fields = {}) - Trav3::POST.call(self, url, fields) + Trav3::REST.post(self, url, fields) end def validate_api_endpoint(input) raise InvalidAPIEndpoint unless /^https:\/\/api\.travis-ci\.(?:org|com)$/.match? input end