JSON API!

[Ilya Sabanin]

Hey guys,

We added a few cool features to Beanstalk API today that I wanted to share

1. JSON output is now available for all API methods.
2. We added new RepositoryImport resource.
3. As well as new Invitation resource.
4. color_label attribute is now available for ServerEnvironment.

So you can now import repositories (via URL only) and invite users. API docs were updated to reflect all the changes:

http://api.beanstalkapp.com

Happy hacking!

Ilya Sabanin
Lead Beanstalk Developer
http://twitter.com/isabanin

[Chris Barr]

Fantastic! You guys have been very busy. JSON is going to make things a lot easier.

I think I spotted a problem with the RepostioryImport resource though - when creating an import  using XML, there is no root element.
The docs show:

POST /api/repository_imports.xml
<repository-id>{REPOSITORY_ID}</repository-id>
<repository-import>
  <uri>http://example.com/path/to/svn/file.dump</uri>
</repository-import>

There has to be a root element - <import> or <repository> or something. The JSON is valid because it doesn't need that root element.

Chris

[Ilya Sabanin]

Chris,

There's a root element in the that example, just not for the "repository-id" attribute as it doesn't belong to the import itself. You can even pass "repository-id" as a GET parameter.

Ilya Sabanin

Lead Beanstalk Developer

http://twitter.com/isabanin 

--
You received this message because you are subscribed to the Google Groups "Beanstalk API Developers" group.
To view this discussion on the web visit https://groups.google.com/d/msg/beanstalkapp-api-developers/-/ZP-3ob-Xm-4J.
To post to this group, send email to beanstalkapp-...@googlegroups.com.
To unsubscribe from this group, send email to beanstalkapp-api-de...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/beanstalkapp-api-developers?hl=en.

[Chris Barr]

Sorry Ilya I don't quite follow - doesn't the repository-id attribute have to be within the repository-import attribute then? There can only be one lone XML attribute encapsulating all the data (as it is for all other POST and PUT API methods sending XML).

I'm not keen on using repository-id as a GET parameter because it doesn't follow convention. Putting it into the URL like it is for creating Releases - ie. POST /api/{REPO_ID}/repository_import.xml - would seem more conventional.

Chris

[Ilya Sabanin]

Sorry, that's what I meant by saying that you can use it as a GET parameter. You can send a request like this:

POST /api/repository_imports.xml?repository_id=34324

The only reason I put it into POST body is because there was not enough space in the docs for a URL that long :) Also, I decided not to use repository prefix because it's not explicit enough. Compare this:

POST /api/repository_imports.xml?repository_id=34324

To this:

POST /api/34324/repository_imports.xml

First version is explicit while the last one is kind of vague. In my opinion prefixes are great for human-readable params, it doesn't make sense to use them for numeric IDs.

Ilya Sabanin

Lead Beanstalk Developer

http://twitter.com/isabanin 

--
You received this message because you are subscribed to the Google Groups "Beanstalk API Developers" group.

To view this discussion on the web visit https://groups.google.com/d/msg/beanstalkapp-api-developers/-/OvcB__q2zdkJ.

[Chris Barr]

Sorry if it seems like I'm going on about this a bit much - but this is totally backward. There are no other methods in the API that send a GET variable with POST data - this would be the first method that does this. And I am simply unable to generate the XML that is given in the docs, because it is not valid XML. It has to be changed.

Taking a different method in the API as an example - creating permissions for a user is based on a repository, but the repository-id is within the <permission> element. So:

POST /api/permissions.xml
<?xml version="1.0" encoding="UTF-8"?>
<permission>
  <user-id type="integer">5638</user-id>
  <repository-id type="integer">11</repository-id>
  <write type="boolean">true</write>
  <server-environment-id type="integer">362</server-environment-id>
</permission>

But following the new conventions of the repository import method, this would be re-written as:

POST /api/permissions.xml?repository_id=11
<?xml version="1.0" encoding="UTF-8"?>
<permission>
  <user-id type="integer">5638</user-id>
  <write type="boolean">true</write>
  <server-environment-id type="integer">362</server-environment-id>
</permission>

Or worse (which is also not valid):

POST /api/permissions.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository-id type="integer">11</repository-id>
<permission>
  <user-id type="integer">5638</user-id>
  <write type="boolean">true</write>
  <server-environment-id type="integer">362</server-environment-id>
</permission>

Please please please change this method to look like this:

POST /api/repository_imports.xml
<repository-import>
  <repository-id>{REPOSITORY_ID}</repository-id>

  <uri>http://example.com/path/to/svn/file.dump</uri>
</repository-import>

Chris

[Björn]

Chris is right. You can't have a POST request have GET parameters.
Parameters in a POST request go in the message body. I can't generate
this XML as well. Just because its not valid.

On Oct 18, 3:47 pm, Chris Barr <chrisba...@gmail.com> wrote:
> Sorry if it seems like I'm going on about this a bit much - but this is

> totally backward. There are *no* other methods in the API that send a GET

> variable with POST data - this would be the first method that does this. And
> I am simply unable to generate the XML that is given in the docs, because it

> is *not valid* XML. It has to be changed.

>
> Taking a different method in the API as an example - creating permissions
> for a user is based on a repository, but the repository-id is within the
> <permission> element. So:
>
> POST /api/permissions.xml
> <?xml version="1.0" encoding="UTF-8"?>
> <permission>
>   <user-id type="integer">5638</user-id>
>   <repository-id type="integer">11</repository-id>
>   <write type="boolean">true</write>
>   <server-environment-id type="integer">362</server-environment-id>
> </permission>
>
> But following the new conventions of the repository import method, this
> would be re-written as:
>

> POST /api/permissions.xml*?repository_id=11*

> <?xml version="1.0" encoding="UTF-8"?>
> <permission>
>   <user-id type="integer">5638</user-id>
>   <write type="boolean">true</write>
>   <server-environment-id type="integer">362</server-environment-id>
> </permission>
>

> *Or worse *(which is also not valid):
>
> POST /api/permissions.xml
> <?xml version="1.0" encoding="UTF-8"?>*
> <repository-id type="integer">11</repository-id>*

> <permission>
>   <user-id type="integer">5638</user-id>
>   <write type="boolean">true</write>
>   <server-environment-id type="integer">362</server-environment-id>
> </permission>
>

> Please please* please* change this method to look like this:
>
> POST /api/repository_imports.xml
> <repository-import>
>   *<repository-id>{REPOSITORY_ID}</repository-id>*

[Ilya Sabanin]

Chris,

Wait, I think you are confused. The reason why "/api/permissions.xml" endpoint is asking for a repository_id to be included inside <permission> tag is because repository_id is part of the Permission's data. For RepositoryImport it's not the case: repository_id is not part of it's data and it's simply required as a prerequisite for that method, a repository must be found before RepositoryImport can be created.

And there are plenty of such methods in the API. Look at every method for ServerEnvironment for example:

http://api.beanstalkapp.com/server_environment.html

They all have REPOSITORY_ID or SERVER_ENVIRONMENT_ID in their URL that's not part of the XML. I will move the repository_id attribute from POST body to URL in that RepositoryImport example to avoid confusion.

Ilya Sabanin

Lead Beanstalk Developer

http://twitter.com/isabanin 

--
You received this message because you are subscribed to the Google Groups "Beanstalk API Developers" group.

To view this discussion on the web visit https://groups.google.com/d/msg/beanstalkapp-api-developers/-/diOoaYjsrY4J.

[Ilya Sabanin]

Can you elaborate, please? I just tried one more time and it worked fine:

http://cl.ly/3U3S1v0i1P1K2a1o0v2K

Ilya Sabanin
Lead Beanstalk Developer
http://twitter.com/isabanin

> --
> You received this message because you are subscribed to the Google Groups "Beanstalk API Developers" group.

[Chris Barr]

"They all have REPOSITORY_ID or SERVER_ENVIRONMENT_ID in their URL that's not part of the XML."

Yes but they are part of the URL, not parameters on the end.

Chris

[Björn]

Now, I am confused.

Take this one for example:

POST /api/{REPOSITORY_ID}/server_environments.xml

<?xml version="1.0" encoding="UTF-8"?>

<server-environment>
<name>The Development</name>
</server-environment>

This is fine. We have a POST request with a message body. The message
body is valid XML.

Now, lets have a look at this one:

POST /api/repository_imports.xml
<repository-id>{REPOSITORY_ID}</repository-id>
<repository-import>

<uri>http://example.com/path/to/svn/file.dump</uri>
</repository-import>

This is not a well-formed XML document. No XML parse would accept
that, because there is no single root element. There is no method like
this in the Beanstalk API and it is the first time this format has
appeared.

<repository-import>
<repository-id>{REPOSITORY_ID}</repository-id>

<uri>http://example.com/path/to/svn/file.dump</uri>
</repository-import>

This one has a single root element and is well-formed.

Now lets get back to POST and GET.

POST /api/permissions.xml*?repository_id=11*
<?xml version="1.0" encoding="UTF-8"?>
<permission>
<user-id type="integer">5638</user-id>
<write type="boolean">true</write>
<server-environment-id type="integer">362</server-environment-id>
</permission>

We have a query string: repository_id=11 and a message body. Form data
should be included in the message body only. So you are right, about
this one. This is not a requirement but a convention. However form
data is only encoded as a query string when the method is GET. This is
the recommend way.

On Oct 18, 4:05 pm, Ilya Sabanin <ilya.saba...@gmail.com> wrote:
> Can you elaborate, please? I just tried one more time and it worked fine:
>
> http://cl.ly/3U3S1v0i1P1K2a1o0v2K
>
> Ilya Sabanin

> Lead Beanstalk Developerhttp://twitter.com/isabanin

[Ilya Sabanin]

Alright, convinced. I will follow the same conventions as in other resources, I'll make repository_id a URL prefix. So the URL will look like this:

http://ilya.bs.local/api/17/repository_imports.xml

Works for you guys?

Ilya Sabanin
Lead Beanstalk Developer

http://twitter.com/isabanin

[Björn]

This works!

https://<host>/api/repositories/<id>/import

This is even better. :-)

- Björn

On Oct 18, 4:44 pm, Ilya Sabanin <ilya.saba...@gmail.com> wrote:
> Alright, convinced. I will follow the same conventions as in other resources, I'll make repository_id a URL prefix. So the URL will look like this:
>
> http://ilya.bs.local/api/17/repository_imports.xml
>
> Works for you guys?
>
> Ilya Sabanin

[Ilya Sabanin]

Björn, yeah, I like that too but it would require to change too many moving parts :) Maybe for the V2 of the API..

Ilya Sabanin
Lead Beanstalk Developer

http://twitter.com/isabanin

[Chris Barr]

Brilliant, thanks Ilya, sorry to be a pain.
On a better note, I should have the Beanstalk PHP API fully up to date by tomorrow with these new methods and json processing.

Chris

[Ilya Sabanin]

Chris, that's great news. I just updated the API to support both new and old way of handling the repository_id attribute. I also updated the docs:

http://api.beanstalkapp.com/repository_import.html

Ilya Sabanin

Lead Beanstalk Developer

http://twitter.com/isabanin 

--
You received this message because you are subscribed to the Google Groups "Beanstalk API Developers" group.

To view this discussion on the web visit https://groups.google.com/d/msg/beanstalkapp-api-developers/-/ASHR2cgtkkkJ.