WebAPI to update project resources file

How about:

POST /api/1/project/name/resources

form-enc:
<URL>

application/yaml (the yaml content type)
(the actual file)

application/xml
(the actual file)

if the post payload is empty, then it defaults back to the url defined in framework.properties (with a log message...actually a log message either way). If it's yaml or xml, it uses that content as the new resource representation

The POST should return a 302 Moved with a location to /api/1/project/name/resources which returns the underly resource.

-Noah

+1

Like the post idea...

but the response should probably not be a redirect to the same URL, that would create a loop.

response should likely be 200. The content could be the resources data, but that could be large. it could also just be the API response XML format.

It also points out that the URL for resource data for a project should be /api/1/project/name/resources, currently the API defines it as /api/1/resources?project=name. We could redefine that or support both (perhaps 302 to the former)

actually the /api/1/resources?project=name is maybe better as the query interface, and /api/1/project/name/resources is the endpoint for update/storage/retrieval

some notes on this:

POST xml or yaml to "/api/1/project/NAME/resources": The content is parsed as resource data, and if valid replaces the existing resources file for the project in current file format

POST form data with param providerURL=<url>, then the resources file is updated from the URL

POST with form data param refresh=true, then the resource file is update from stored provider URL if set

all these respond with 200 and API XML response data.

GET returns the same data as /api/1/resources?project=name i.e. the resources data, and format=yaml/xml produces the requested format.

I think the /project/NAME/resources endpoint should not be overloaded so much.

I would like to split out the two Resource refresh requests, perhaps as /project/NAME/resources/refresh

Verbs in urls equals much public giggling and pointing.

Also the 302 would redirect to a GET, basically returning the results.

Yes you are right, 302 does result in GET in browsers (curl actually has a
special flag to change this behavior to follow RFC and use original method)

I still think the response should be 200 with API xml content (explicit
confirm/fail/error response, consistent with other endpoints), but I can
make it do 302. It raises the question of what format the resources should
be returned in. If you POST yaml content, are you expecting yaml back?
(i.e. redirect to /resources?format=yaml)

A separate endpoint for simply refreshing the resources via a user URL or
the pre-configured URL doesn't sound good to you? Our api is not very RESTy,
but the overloaded endpoint seems decidedly un-resty.

(Btw, our API must seem hilarious..we already have numerous verbs in the API urls...so does twitter).

The 302 is a nice to have. Return the results should be based on the accept header from the client. If they want xml or json, then that's how it's served. The requires content negotiation on the server.

Returning the results after a post, but why not just return a redirect and let the GET handler do the same thing. The client will do the right thing.

I realize that the goal is not to be a REST api, hence the WEB API designation, but that doesn't stop people from comparing. Twitter gets heat for their API, but they're twitter.

the 200 would result in the standard response format: http://rundeck.org/docs/RunDeck-Guide.html#response-format

if the client wants the resources they can GET it afterwards, and be explicit about desired format.

still unsure about refresh action endpoint

-1 on the refresh action endpoint.

separate endpoint corresponds to the single GUI button to do the same thing, so i think it makes sense.

independent of that tho, another question:

should the Refresh action allow providerURL of file:// as well as http(s)?

+1, separate endpoint for refresh

Yes...definitely allow both file:/// and http:///. Rundeck doesn't run as a privileged user, but some additional security checks would be nice to have.

For example, an additional check should be made to prevent rundeck from making requests to some random endpoint. Something like:

framework.properties.secure_domain.0=https://internal.host.network: (regex or glob here)
framework.properties.secure_domain.1=file:///var/rundeck/* (regex or glob here)

the above is nice to have considering the users are authenticated before being able to make the call.

-Noah

ok, allowing file as well as http(s).

secure_domain is a good idea: add another issue req?

+1 for separate ticket for this and refresh endpoint then.

+1 on both.

(from [dadc15f854ca47bc23a11e6908d18e23418fd743]) Add /api/project/NAME/updateResources endpoint [#250 WebAPI to update project resources file] https://github.com/dtolabs/rundeck/commit/dadc15f854ca47bc23a11e690...

(from [e725c5776fbecc300bed39446bd2861af486a0d3]) Add docs for /api/project/NAME/updateResources endpoint [#250 WebAPI to update project resources file] https://github.com/dtolabs/rundeck/commit/e725c5776fbecc300bed39446...