API V3 : A complete reimagining of what the Travis CI API should be

[carlad]

After many months of amazing work by the entire Travis team, we're super excited to announce the release of the Travis CI API Version 3!

Central to this release is an improved and modernized API experience, with faster response times, and a dramatically cleaner code base.

As our UI is based on Ember, and as such is a rich javascript codebase, so a great API is even more important to us!

Some of the topics we focused on during development were:

• an API that was functional and well structured
• standardized formats and RESTful endpoints
• responses that are discoverable and self-documenting
• consistent and informative error messages
• all the hypermedia features expected from a modern API

We could go on for pages about why we love this API so much, but why not try it out for yourself! You can head over to our documentation for more information, or read our Blog post announcement which has more information about our API explorer.

Please leave all feedback as comments here, or if you run into a bug, please report it to our support team.

[alanhdu]

This is great! I'm definitely loving the new API -- it's definitely cleaner and more consistent than the old API. I do have a couple suggestions/feature requests though:

1. The old API included the build config for jobs, but it looks like it's missing in the API v3. Would it be possible to add it back in? (Or at the very least get the operating system and the environment variables set?)
2. This might be a stretch, but would it be possible to document nullable vs non-nullable fields? It'd be super nice to know what information is guaranteed to be there and what information is conditional.
3. Related to the above, would it be possible to document all the possible values of certain fields? Like, I assume that the state field for jobs can only take on a handful of values, and it'd be great to explicitly list them all out.
4. On https://developer.travis-ci.org/resource/builds, it'd be great if the link for the [Builds] type led to https://developer.travis-ci.org/resource/build#Build instead of to the same page (ditto for other "plural" pages like https://developer.travis-ci.org/resource/jobs)
5. When a resource doesn't have an active representation, it might be good to just not display anything instead of showing a "Document representations/active not found" error and repeating the standard representation table -- I at least was confused by this for a while.
6. There are a couple fields that have "Unknown" types, which is a little strange (e.g. pull_request_title and pull_request_number for https://developer.travis-ci.org/resource/build#Build).

All in all though, great work! The eager loading in particular is super exciting 🎆.

[carlad]

Hey @alanhdu thanks so much for the feedback. We're glad you're liking things so far.

Regarding your suggestions/requests:

1. We already have a ticket for this but are awaiting some imminent changes to travis-yaml, which will impact how we process the repo's .travis.yml and create the job config. Stay tuned for this addition to v3.

2. All attributes listed in a representation will be returned regardless of whether they contain a value or are nil (in which case nil is returned). Additional attributes are only returned when ?included in the request. So documenting whether an attribute can be nil is not necessary, as it will always be in the response. However, I may have misunderstood what you meant by nullable...

3. We can look into this. Some fields have infinite possible values :), so we'd probably need to limit which fields we document in this way. state is definitely a good candidate. Can I ask how you would use this information? Just to get a better idea of your needs around this.

4. This was actually the intention, and we've uncovered the bug that was causing the wrong links to be generated. Thanks for reporting this :)

5. This has already been addressed by this PR: https://github.com/travis-ci/travis-api/pull/481

6. Thanks too for spotting these. They've been updated to show their correct types.

[alanhdu]

Hi @carlad! I'm glad this was helpful 😹.

So my use-case for (2) and (3) is trying to deserialize the JSON responses into a Rust struct -- basically, I'd love to know whether to deserialize a field into a String, Option<String> (which is either a String or None, which is what I mean by "nullable"), or into a custom enum (for e.g. state). Strictly speaking, I can just deserialize everything into an Option<String>, but I'd love to enforce more type safety if I can!

One more thing that I just noticed -- when I click on one of the links in the sidebar, the page doesn't scroll to the top -- that means if I click on something like Settings, the screen doesn't really show that much interesting information (see attached screenshot). I think this only happens with Firefox -- with Chrome, clicking on the links automatically scrolls up to the top (this is with Firefox Aurora on Ubuntu 16.04).

[alorma]

Hi

Any plans to adopt GraphQL as api provider?

[joshk]

Hi @alorma. Thanks for the question. We don't have plans for GraphQL at this stage. I'm not sure if we will implement GraphQL support, but it may be something for us to look into once our V3 API has had wider adoption.

[joshk]

With v3 API released and working smoothly, I'm going to close this Beta Feature issue 🎉

If you have any thoughts/feedback/issues/concerns/dance-moves you would like to share with us, please open an issue at https://github.com/travis-ci/travis-ci/issues

Huzzah!

[isabellachen]

Hi everyone! Where can I find the documentation for eager loading and the include param in the API?

https://developer.travis-ci.com/eager-loading#eager%20loading

Thanks!

@carlad @joshk

[carlad]

Hey @isabellachen

The page you link to is the documentation we currently have.

More information about what attributes are available for each resource can be found on the individual resource page.

For example, when querying the /repo/[:id]/branch/master endpoint, it would be possible to include any build attribute listed on the page describing the build resource: https://developer.travis-ci.com/resource/build#standard-representation

You can test this in the API Explorer like so: https://developer.travis-ci.org/explore/repo/59/branch/master?include=build.jobs

or

https://developer.travis-ci.org/explore/repo/59/branch/master?include=build.commit

Does that help? Was there specific information you were wanting to eager load/include in a request?

[isabellachen]

What I would like to have the the github_id of the person that created the build, is that possible? Could I also load several attributes? Like both the build.created_by and build.jobs at the same time? How would I do it? Thank you :)

[carlad]

I'm not sure about the github_id of the build creator - I can check on that, however created_by and jobs is already returned in the standard representation of a build:

https://developer.travis-ci.org/explore/build/86601346

Is that the endpoint are you querying?

[isabellachen]

Right now I'm able to get either the created_by or jobs when I ping the API for all the requests of a repo repo/{repo.id}/requests?include=build.created_by, it would be nice to get both when I make the call for all the requests...

[carlad]

Try this repo/{repo.id}/requests?include=build.created_by,build.jobs

It might not be the most efficient query, depending on how many requests are being returned, and how many jobs each of those requests has. You can see an example of the time this query takes: https://developer.travis-ci.org/explore/repo/891/requests?include=build.created_by,build.jobs

[kopax]

Dear Travis,

I have been trying to create a new environment twice and it is impossible:

Without it, it is impossible to automatically configure travis automatically for all our repos that we want release opensource.

I dont understand but travis+coveralls close their API but that would benefit the community at every point so please allow me to ask why?

[carlad]

Hi @kopax - thanks for the comment. Just to clarify, you want to CREATE an environment variable with our API? It's not totally clear from the screenshots here what you are wanting to do.

[kopax]

@carlad, I want to push from gitlab/gitlab-ci to github/travis-ci

We need to create variables and travis documentation only show how to update.

We have seen in the developer tools on travis website that the query used to create env by travis is using POST.

We changed all our PATCH to POST:

  # Request that create
  curl "https://api.travis-ci.org/settings/env_vars?repository_id=${scope}/${name}" \
  -H "Authorization: token ${TRAVIS_CI_TOKEN}" \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data-binary '{"env_var":{"name":"NPM_TOKEN","value":"'${NPM_TOKEN}'","public":false,"repository_id":"'${scope}/${name}'"}}' \
  --compressed
  curl "https://api.travis-ci.org/settings/env_vars?repository_id=${scope}/${name}" \
  -H "Authorization: token ${TRAVIS_CI_TOKEN}" \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data-binary '{"env_var":{"name":"GH_TOKEN","value":"'${GH_TOKEN:-GITHUB_TOKEN}'","public":false,"repository_id":"'${scope}/${name}'"}}' \
  --compressed

#  # Request that update
#  curl -sS -X PATCH \
#  -H "Content-Type: application/json" \
#  -H "Travis-API-Version: 3" \
#  -H "Authorization: token ${TRAVIS_CI_TOKEN}" \
#  -d '{ "env_var.value": "'${NPM_TOKEN}'", "env_var.public": false }' \
#  https://api.travis-ci.com/repo/${scope}/${name}/NPM_TOKEN
#
#  curl -sS -X PATCH \
#  -H "Content-Type: application/json" \
#  -H "Travis-API-Version: 3" \
#  -H "Authorization: token ${TRAVIS_CI_TOKEN}" \
#  -d '{ "env_var.value": "'${GH_TOKEN:-GITHUB_TOKEN}'", "env_var.public": false }' \
#  https://api.travis-ci.com/repo/${scope}/${name}/GH_TOKEN

The thing is those POST request initially needs to have in query string the repository_id which we don't know how to get. Could you help us out?

[carlad]

Thanks for the additional info @kopax.

It's also possible to use the repository 'slug' in the request uri. An example for the rails/rails repository would be like so: .../repo/rails%2Frails/env_vars

(see the second example at: https://developer.travis-ci.com/resource/env_vars#create)

Note that the 'slug' is a combination of the organisation/user name and the repo name, with the / character being replaced with %2F.

Does that help at all?

[kopax]

@carlad not really, we have tried the slugs and we were having not found error.

This did the trick:

  travisRepositoryId=$(curl -sS https://api.travis-ci.org/repos/${scope}/${name} -H "Authorization: token ${TRAVIS_CI_TOKEN}" | jq -r .id)

  # Now create
  curl "https://api.travis-ci.org/settings/env_vars?repository_id=${travisRepositoryId}" \
  -H "Authorization: token ${TRAVIS_CI_TOKEN}" \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data-binary '{"env_var":{"name":"NPM_TOKEN","value":"'${NPM_TOKEN}'","public":false,"repository_id":"'${scope}/${name}'"}}' \
  --compressed
  curl "https://api.travis-ci.org/settings/env_vars?repository_id=${travisRepositoryId}" \
  -H "Authorization: token ${TRAVIS_CI_TOKEN}" \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data-binary '{"env_var":{"name":"GH_TOKEN","value":"'${GH_TOKEN:-GITHUB_TOKEN}'","public":false,"repository_id":"'${scope}/${name}'"}}' \
  --compressed

[carlad]

@kopax also check that the uri is requesting the correct platform (either travis-ci.com or travis-ci.org)

I can see in the example requests you've posted that sometimes you are requesting .com and sometimes .org. The not found error might be happening because you're hitting the wrong platform.

[kevinburke]

I'm not sure if this is the right place to comment, as this issue is closed. Still, https://developer.travis-ci.com/ links here so I'll leave my feedback here.

I have a command line tool - also named travis - that I use mainly in two ways:

• travis wait - push a commit, wait for the running Travis build for the commit to complete, download error logs (if any) and display them in the console.

• travis open - open the build for the current commit in the browser.

The tool is available from here: https://github.com/kevinburke/travis.

How this works when you type travis wait is:

• find the current Git branch
• issue GET /builds?branch.name={branch name}
• check whether the SHA of the latest build matches the tip SHA on the given branch
• continually poll that build until it reaches a terminal state
• download error logs

I'm running into problems when trying to get builds for a branch when the .travis.yml has this setting:

# Build on merges to master
branches:
  only:
    - master

Basically if I have a pull request open on a branch named, say, fix-tests, a build happens, but it's difficult to determine from the API which branch is associated with which project.

I see a "event_type": "pull_request" build, but it's basically impossible to correlate this object with the Git branch that I'm on, or the commit SHA that I pushed. The branch isn't present in the build object, and the SHA is generated from a merge commit so it's not actually the SHA that I pushed to Github.

In theory I guess I could also hit the Github API and figure out which pull request correlates with which branch, but that's a huge pain, and requires 1 request per Travis build in the response. Also it would require me to ask console users for a Github token as well which seems unnecessary.

If there's a pull request open for a Git branch it would be nice if there was some way to correlate the Travis build for the pull request with the Git branch that opened the PR/triggered that build.

[joshk]

Hi @kevinburke

Sorry for our lack of response. I think it would be best to ask this question on https://travis-ci.community so we can make sure it is escalated and tracked, especially as this issue for the API is closed.

[TryfonAll]

Good work

[jorgejbj1]

Perfect work

[mgedmin]

https://developer.travis-ci.com/ tells me I should leave feedback here, so here it is: if you open that site in a browser page that's too narrow (I press Super+Right to tile the window to the right half of my 1920x1080 GNOME desktop), the sidebar with the menu disappears completely, leaving you with just a single piece of text that doesn't actually tell you how to do any of the things it claims the API allows you to do. I was confused for about 15 minutes until I thought to maximize the window.

[jianguda]

Hey @carlad , I am building one GitHub app to monitor travisCI's build info, and I use my travis token to request API v3. However, I found that I can only get results from myself, not from others (other users who installed my GitHub app). So, do I have to use other users' tokens to get their respective data?

For example, I am A, other user who installed my GitHub app are B and C. I can get my travis data (like buildInfo, builds, etc) with my travis token, but get Error requesting Travis API StatusCodeError: 403 - "access denied" when try to get travis data of B or C. So, do I have to get B's travis token to request API to get B's travis data and get C's travis token to request API to get C's travis data?

If I do not use travis API, but visit travis.org manually, I can see B or C's travis data. Please tell me, thanks!

[carlad]

Hi Jian,

I no longer work at Travis-CI, but I believe you do need the tokens corresponding to the other users to see their builds. I suggest emailing support@travis-ci.com to confirm this.

Have a great day.

Carla

On Tue, 14 Jan 2020 at 19:30, Jian GU notifications@github.com wrote:

Hey @carlad https://github.com/carlad , I am building one GitHub app to monitor travisCI's build info, and I use my travis token to request API v3. However, I found that I can only get results from myself, not from others (other users who installed my GitHub app). So, do I have to use other users' tokens to get their respective data?

For example, I am A, other user who installed my GitHub app are B and C. I can get my travis data (like buildInfo, builds, etc) with my travis token, but get Error requesting Travis API StatusCodeError: 403 - "access denied" when try to get travis data of B or C. So, do I have to get B's travis token to request API to get B's travis data and get C's travis token to request API to get C's travis data?

If I do not use travis API, but visit travis.org manually, I can see B or C's travis data. Please tell me, thanks!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/travis-ci/beta-features/issues/6?email_source=notifications&email_token=AANMOX27HNML34YNXHBOVGTQ5YAETA5CNFSM4DCIPMZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEI5UP7Q#issuecomment-574310398, or unsubscribe https://github.com/notifications/unsubscribe-auth/AANMOX6P5O4VK4DJ6CB36JLQ5YAETANCNFSM4DCIPMZA .

[vimal2612]

Not able to access API explorer. Asks me to log in, when I log in though, it takes me to https://app.travis-ci.com/ and when I go to docs it automatically gets logged out.