Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document and support the ATC REST API #1122

Open
vito opened this issue May 9, 2017 · 18 comments

Comments

@vito
Copy link
Member

commented May 9, 2017

No description provided.

@vito vito changed the title Provide ATC (REST) API docs Document and support the ATC REST API Oct 2, 2017

@vito vito added the core/api label Oct 2, 2017

@vito vito removed the enhancement label Nov 28, 2017

@trobert2

This comment has been minimized.

Copy link

commented Apr 9, 2018

any progress on this issue?
inb4 "nobody likes writing docs"

@scarytom

This comment has been minimized.

Copy link

commented Oct 10, 2018

I guess this is the closest thing we have to documentation for the API: https://github.com/concourse/concourse/blob/master/atc/routes.go#L106

@jama22

This comment has been minimized.

Copy link
Member

commented Oct 26, 2018

Whelp, I know its been a while but we're actually re-visiting this now. Since we originally wrote the issue, we've held off from doing this in favour of implementing Users and RBAC.

We've finished both of those features now so we're starting to revisit what it will take to build up a sustainably maintained and documented API. As a first step, we're asking for feedback from any Concourse users who have written any scripts/apps/code against the existing Concourse API. If you have any feedback, please comment below!

@ifraixedes

This comment has been minimized.

Copy link

commented Oct 29, 2018

An Open API document would be highly appreciated. It will allow knowing the request and response payloads on each route without having to dig into the Go source code.

On the other hand (and probably in a second stage) some more source comments (GoDoc) would also be appreciated.

@murac

This comment has been minimized.

Copy link

commented Nov 9, 2018

Even just for the time being, an example of fetching a Bearer token via script would be great. Anyone have any leads there?

@StevenArmstrong

This comment has been minimized.

Copy link

commented Nov 9, 2018

@dwelch2344

This comment has been minimized.

Copy link

commented Nov 16, 2018

Even starting with a postman collection or something would be awesome. TBO that’s my preferred docs these days

@dwelch2344

This comment has been minimized.

Copy link

commented Nov 16, 2018

It works like a charm. Syntax was a little hard to understand in the dogs when I first read through. Might open a PR for a little more clarity for newbies like me. Would that be received well? Either way, thanks for the awesome library!

@scarytom

This comment has been minimized.

Copy link

commented Nov 19, 2018

Here is a bearer token request using curl

curl -v \
-X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
--user 'fly:Zmx5' \
--data-urlencode 'username=foo' \
--data-urlencode 'password=bar' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid profile email federated:id groups' \
'https://my-concourse.com/sky/token'
@vergissberlin

This comment has been minimized.

Copy link

commented Jan 17, 2019

An API documentation is created very easily with swagger. You can also generate code with it.

@BlacktoBlue

This comment has been minimized.

Copy link

commented Jan 18, 2019

@scarytom in that post what does is user and scope?

@predatorian3

This comment has been minimized.

Copy link

commented Feb 4, 2019

@scarytom , could you explain or elaborate on your cURL example? Why use two username and passwords, and what is the scope coming from?

@scarytom

This comment has been minimized.

Copy link

commented Feb 4, 2019

@BlacktoBlue @predatorian3 You should ask these questions of @StevenArmstrong, as my curl is little more than a re-work of his python example.

As far as I understand it, the ''fly', 'Zmx5`` combo is simply a hard-coded basic http auth inside all concourse deployments -- no idea if that's configurable or not. The secure login cones from the other pair in the POST form. I can't tell you much about scope.

@StevenArmstrong

This comment has been minimized.

Copy link

commented Feb 4, 2019

@SvenDowideit

This comment has been minimized.

Copy link

commented Mar 5, 2019

for those that come later - its also excellent to know that fly has a --verbose flag that will show you the HTTP request and responses that it makes - ie, the client is self documenting, the only hard thing is discovering that it does it :)

--verbose              Print API requests and responses
@iornstein

This comment has been minimized.

Copy link

commented Jun 18, 2019

@SvenDowideit (or anyone else) how do we add the authorization to requests like fetching the old config or PUT-ing new config for pipelines? I hit these end points and get 401. For example

GET {{local-concourse-url}}/api/v1/teams/main/pipelines/hello-world/config

Results in a 401. What is the authorization I am supposed to add? And how do I add it to the request? I tried the concourse user/password as Basic Auth params to the request and also tried adding headers username and password.

@fewknow

This comment has been minimized.

Copy link

commented Jul 9, 2019

Fetching bearer token with basic auth(local)

#!/bin/bash

## Variables required  #need to update these to take inputs for getting token per team and target.
CONCOURSE_URL="http://concourseci.XXXXXX.XXX"
CONCOURSE_USER="XXXX"
CONCOURSE_PASSWORD="XXXX"
CONCOURSE_TEAM="XXXXXX"
CONCOURSE_TARGET=XXXXXX

function get_token() {
  ## Create a file named token that will be used to read and write tokens
  touch token

  ## extract the LDAP authentication url and write to token file
  LOCAL_AUTH_URL=$CONCOURSE_URL$(curl -b token -c token -L "$CONCOURSE_URL/sky/login" -s | grep "/sky/issuer/auth/local?" | awk -F'"' '{print $4}')
  echo "url is $LOCAL_AUTH_URL"
  # login using username and password while writing to the token file
  curl -s -o /dev/null -b token -c token  -L --data-urlencode "login=$CONCOURSE_USER" --data-urlencode "password=$CONCOURSE_PASSWORD" "$LOCAL_AUTH_URL"

  ATC_BEARER_TOKEN=`grep 'Bearer' token | cut -d\   -f2 | sed 's/"$//'`
  echo $ATC_BEARER_TOKEN
}

Here is a link for LDAP : #1487

@vito vito added this to Planned in API v2 Jul 31, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
You can’t perform that action at this time.