Home » Developers » Shapeways API » Java API
Search Search  
Show: Today's Messages    Show Polls    Message Navigator
Java API [message #65077] Thu, 28 March 2013 21:36 UTC Go to next message
avatar entertailion  is currently offline entertailion
Messages: 71
Registered: February 2013
Go to my shop
Member
I'm working on a Java library to call the Shapeways API. I'm planning on using it for an Android app. I've got the basic OAuth flows working but I have some questions:
1. Why is the API based on OAuth 1.0? Most other web API's are based on either OAuth 1.0a or OAuth 2.0. Any plans to update?
2. There are some inconsistencies for the path formats for invoking the API. For example, "/materials/v1" for materials and "/material/{materialId}/v1" for a particular material makes sense. But then "/printers/v1" for printers and "/printers/{printerId}/v1" for a printer doesn't follow the same singular pattern (i.e "/printer/{printerId}/v1").
3. The JSON format of the results are not consistent. For example, the list of printers ("/printers/v1") are returned as a JSON array, but the list of materials ("/materials/v1") are not using the same array ("[ ]") notation.
4. The results contain duplicated data. For example, the list of all materials ("/materials/v1") has an ID for each material that is duplicated. The result for "/api/v1/" returns duplicated data about the rate limits.
5. Why isn't HTTPS supported for the API?

I'm trying to come up with a generic design to invoke the API and parse the JSON responses, but these inconsistencies is making it more difficult than it needs to be. Are there any plans to update the API?

Thanks

[Updated on: Thu, 28 March 2013 23:43 UTC]


- Leon
http://www.shapeways.com/shops/entertailion
http://leonnicholls.com
Re: Java API [message #65138 is a reply to message #65077 ] Fri, 29 March 2013 21:09 UTC Go to previous messageGo to next message
avatar admin_nathan  is currently offline admin_nathan
Messages: 17
Registered: December 2011
Go to my shop
Junior Member
I code here
Hey there,

entertailion wrote on Thu, 28 March 2013 21:36

I'm working on a Java library to call the Shapeways API. I'm planning on using it for an Android app. I've got the basic OAuth flows working but I have some questions:
1. Why is the API based on OAuth 1.0? Most other web API's are based on either OAuth 1.0a or OAuth 2.0. Any plans to update?

Shapeways API is OAuth1.0a compliant.

Quote:

2. There are some inconsistencies for the path formats for invoking the API. For example, "/materials/v1" for materials and "/material/{materialId}/v1" for a particular material makes sense. But then "/printers/v1" for printers and "/printers/{printerId}/v1" for a printer doesn't follow the same singular pattern (i.e "/printer/{printerId}/v1").

There was a bug in the docs - it should be "/materials/{materialId}/v1". /material/ and /printer/ also work for the time being, but those URIs will be phased out eventually, so please do not rely on them.

Quote:

3. The JSON format of the results are not consistent. For example, the list of printers ("/printers/v1") are returned as a JSON array, but the list of materials ("/materials/v1") are not using the same array ("[ ]") notation.

Materials are intentionally returned as an object of objects. The key value is the material id and the same pattern is used for material objects in /models requests. However, you make a good point about consistency of lists and I will raise this concern.

Quote:

4. The results contain duplicated data. For example, the list of all materials ("/materials/v1") has an ID for each material that is duplicated. The result for "/api/v1/" returns duplicated data about the rate limits.

The materials object of objects uses material id as the key, and also includes the material id in the object itself. This is intentional.
/api/v1 returns duplicate data for backwards compatibility reasons and will be phased out. Only the rate limit object should be used. Please use the developer docs (http://developers.shapeways.com/docs) as a guide for request parameters and return values that you can expect to be supported.

Quote:

5. Why isn't HTTPS supported for the API?

I believe that HTTPS protocol for the API will be supported in the future.

Quote:


I'm trying to come up with a generic design to invoke the API and parse the JSON responses, but these inconsistencies is making it more difficult than it needs to be. Are there any plans to update the API?

Aside from the LIST materials object (instead of the typical LIST array), do you still have any consistency concerns? Much thought goes into the nomenclature and structure of the API. I can't promise that you'll be able to completely rely on a generic design, but our design decisions should be intuitive enough for you to know what to expect. Of course, if they aren't, please do let us know Smile

Quote:

Thanks


Thank you!

- Nathan
Re: Java API [message #65144 is a reply to message #65138 ] Fri, 29 March 2013 23:25 UTC Go to previous messageGo to next message
avatar entertailion  is currently offline entertailion
Messages: 71
Registered: February 2013
Go to my shop
Member
Thanks for the detailed response.

admin_nathan wrote on Fri, 29 March 2013 21:09

Shapeways API is OAuth1.0a compliant.

All the Java libraries I found for OAuth 1.0a and 2.0 requires the request, access and authorization URL's to be provided. Since the Shapeways docs only mentioned the request and access URL's, I assumed it was OAuth 1.0.

Quote:

There was a bug in the docs - it should be "/materials/{materialId}/v1". /material/ and /printer/ also work for the time being, but those URIs will be phased out eventually, so please do not rely on them.

The only path that is left singular is for prices ("/price/v1").

Quote:

Materials are intentionally returned as an object of objects. The key value is the material id and the same pattern is used for material objects in /models requests. However, you make a good point about consistency of lists and I will raise this concern.

The JSON libraries I tried prefers the array notation and can automatically do data binding. I had to manually parse the "objects of objects" notation.

Quote:

Aside from the LIST materials object (instead of the typical LIST array), do you still have any consistency concerns? Much thought goes into the nomenclature and structure of the API. I can't promise that you'll be able to completely rely on a generic design, but our design decisions should be intuitive enough for you to know what to expect. Of course, if they aren't, please do let us know Smile

I have seen some other inconsistencies. I'm making my way through all of the API's. I'll make a list and post it when I'm done.

Thanks


- Leon
http://www.shapeways.com/shops/entertailion
http://leonnicholls.com
Re: Java API [message #65191 is a reply to message #65144 ] Sat, 30 March 2013 18:15 UTC Go to previous messageGo to next message
avatar entertailion  is currently offline entertailion
Messages: 71
Registered: February 2013
Go to my shop
Member
For the " /models/v1/" API, the model attributes all have "model" prefixes like "modelVersion" and "modelTitle". But the "/materials/v1" API does not use prefixes for most of the attributes like "title" and "swatch". It probably makes sense to have a consistent naming convention for attributes across all API calls.

The "nextActionSuggestions" response value isn't consistent. The "/api/v1/" returns a value. For the "/printers/v1" API, the doc says it should have a "nextActionSuggestions" response value, but I don't get any. For some of the other API calls like "/models/v1/" it always has an empty value. Not a critical issue since its unclear why this attribute would be useful especially for a native app.

Error handling isn't documented for the API. The only response status that is documented is the "result" field and only the "success" value is mentioned for all the API calls. What is the expected response for invalid parameters, missing parameters or server-side errors? Are error codes used or are HTTP response codes used?

I've open sourced the code for an Android app that calls the Shapeways API: https://github.com/entertailion/Android-Shapeways

The GET API calls are working. I can't get the POST API calls to work; not sure what the issue is. I'm not an OAuth expert and since I couldn't get the OAuth libraries to work with the Shapeways API, I had to cobble some client code together to make it work.

Thanks

[Updated on: Sat, 30 March 2013 22:02 UTC]


- Leon
http://www.shapeways.com/shops/entertailion
http://leonnicholls.com
Re: Java API [message #65217 is a reply to message #65191 ] Sun, 31 March 2013 01:27 UTC Go to previous messageGo to next message
avatar entertailion  is currently offline entertailion
Messages: 71
Registered: February 2013
Go to my shop
Member
I've updated the app code to use a hybrid approach for OAuth: the request token, access token and authorization is done with my client-side code; then I use an OAuth library for the rest of the API calls using the access token and secret.

I can now see the errors generated when I do a POST API call. For example, if I call the "/orders/cart/v1" API, I get the following:
{"result":"failure","reason":"\n Field <modelId> is required, but missing."}

However, I did pass the "modelId", "materialId" and "quantity" parameters to the POST, so I'm confused why there is an error.

Also, I'm now using the Apache Commons HTTP library, since there's a bug in Android's java.net.HttpURLConnection that keeps it from working with some service providers. I've checked in the latest code: https://github.com/entertailion/Android-Shapeways

Thanks


- Leon
http://www.shapeways.com/shops/entertailion
http://leonnicholls.com
Re: Java API [message #65244 is a reply to message #65217 ] Sun, 31 March 2013 19:36 UTC Go to previous messageGo to next message
avatar entertailion  is currently offline entertailion
Messages: 71
Registered: February 2013
Go to my shop
Member
I got the POST API calls working. I had been assuming the parameters were passed as HTTP parameters, but they need to be encoded in JSON and submitted as the body of the POST request.


- Leon
http://www.shapeways.com/shops/entertailion
http://leonnicholls.com
Re: Java API [message #65248 is a reply to message #65244 ] Sun, 31 March 2013 21:23 UTC Go to previous messageGo to next message
avatar admin_nathan  is currently offline admin_nathan
Messages: 17
Registered: December 2011
Go to my shop
Junior Member
I code here
entertailion wrote on Sun, 31 March 2013 19:36

I got the POST API calls working. I had been assuming the parameters were passed as HTTP parameters, but they need to be encoded in JSON and submitted as the body of the POST request.

Good work!

Invalid requests should return a 500 code along with the reason that the request failed (if available). Rate limited requests will return a 429. Oauth related errors return 401 and unimplemented method errors return 405.

The API docs page does not contain error responses, although the API discovery system (learn more about that on the getting started page http://developers.shapeways.com/getting-started) does reveal the basic error response.

- Nathan
Re: Java API [message #65257 is a reply to message #65248 ] Sun, 31 March 2013 22:02 UTC Go to previous messageGo to next message
avatar entertailion  is currently offline entertailion
Messages: 71
Registered: February 2013
Go to my shop
Member
More comments:
1. The documentation should show examples of the parameters that need to be passed to the API and show examples of the expected response from the API. For example, the order list of cart items ("GET /orders/cart/v1") and list of models ("GET /models/v1/") are not documented.
2. "GET /models/{modelId}/info/v1" requires the "modelId" parameter. Since the "modelId" is part of the path, its not clear why the id needs to be duplicated in the request. My testing shows it works even if the parameter isn't provided. The "DELETE /models/{modelId}/v1/" API requires a "modelId" parameter but I don't think HTTP allows that for DELETE (The Apache HTTP library doesn't allow DELETE requests to set a body)
3. I uploaded various model file names like "original, id=52936.stl" and the JSON results and parsing were all good. Looks like the API handles special characters.
4. It would be great if there was a developer sandbox or test account support so that developers can test orders without using real money.

I've updated the Android example app with the latest code: https://github.com/entertailion/Android-Shapeways
The app can do OAuth and the various GET, POST and DELETE API's. I'm planning to add more features to the app like a storefront, shopping cart and STL viewer.


- Leon
http://www.shapeways.com/shops/entertailion
http://leonnicholls.com
Re: Java API [message #65528 is a reply to message #65257 ] Fri, 05 April 2013 10:01 UTC Go to previous messageGo to next message
avatar hans.lambermont  is currently offline hans.lambermont
Messages: 48
Registered: June 2010
Go to all my models
Member
I work here
entertailion wrote on Sun, 31 March 2013 22:02

1. The documentation should show examples of the parameters that need to be passed to the API and show examples of the expected response from the API. For example, the order list of cart items ("GET /orders/cart/v1") and list of models ("GET /models/v1/") are not documented.


They are documented in the JSON discovery at http://api.shapeways.com/orders/cart/v1 and http://api.shapeways.com/models/v1 . (You might need a JSON View addon for your browser , get it at https://www.google.com/search?q=JSONView)
The html documentation should also have this info, I'll raise that point internally.

entertailion wrote on Sun, 31 March 2013 22:02

2. "GET /models/{modelId}/info/v1" requires the "modelId" parameter. Since the "modelId" is part of the path, its not clear why the id needs to be duplicated in the request. My testing shows it works even if the parameter isn't provided. The "DELETE /models/{modelId}/v1/" API requires a "modelId" parameter but I don't think HTTP allows that for DELETE (The Apache HTTP library doesn't allow DELETE requests to set a body)



The idea is that the modelId is only given in the path. From http://api.shapeways.com/models/v1 :
"parameters": {
    "modelId": {
        "type": "int",
        "description": "Model id",
        "location": "path",
        "dependencies": "required"
    }
},


entertailion wrote on Sun, 31 March 2013 22:02

3. I uploaded various model file names like "original, id=52936.stl" and the JSON results and parsing were all good. Looks like the API handles special characters.



I'll raise this internally. I think we should have a whiltelist of allowed characters.

entertailion wrote on Sun, 31 March 2013 22:02

4. It would be great if there was a developer sandbox or test account support so that developers can test orders without using real money.



Yes, we want to add this.

-- Hans
Re: Java API [message #98413 is a reply to message #65257 ] Thu, 11 September 2014 09:50 UTC Go to previous messageGo to next message
avatar leforthomas  is currently offline leforthomas
Messages: 17
Registered: March 2014
Go to all my models
Junior Member
Hi,

I had a good look at your Android library, thanks a lot for making it open source.

I started (and would like to finish) building my own Java library and am currently stuck with the same problems you had on POST. My GET commands work but not my POSTs. I was hoping you could have a quick look and let me know if there is anything obviously wrong with my implementation.

I am basing my library on scribe, which is quite popular for Oauth, may be you tried it?

First I create my oAuthRequest
OAuthRequest oAuthRequest = new OAuthRequest(Verb.POST, serviceURL);
I then add the parameters to the body as json encoded
oAuthRequest.addPayload(parameters.toJSONString());
I set the headers
oAuthRequest.addHeader("Content-Type", "application/json; charset=utf-8");
oAuthRequest.addHeader("Accept", "application/json");
and sign my request
service.signRequest(accessToken, oAuthRequest);
and finally send my request
Response oAuthResponse = oAuthRequest.send();

The response is always 500 Internal Server error.

If I look at the actual message sent,
(1) body content is my json encoded string, eg {"modelId":1773183} for the post cart.
(2) Url is my API endpoint, eg http://api.shapeways.com/orders/cart/v1
(3) My headers are set for content type and accept and the OAuth Authorisation header is as follows
Authorization=OAuth oauth_signature="UpmlcoxxxxxxxxxxxxjYY%3D", oauth_version="1.0", oauth_nonce="2003439524", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="45bxxxxxxxxxxxxxxxxxxxd58d308", oauth_token="e3aebxxxxxxxxxxxxxxxxxxx03a2af2", oauth_timestamp="1410427574"

Thanks!

Re: Java API [message #98421 is a reply to message #98413 ] Thu, 11 September 2014 13:09 UTC Go to previous messageGo to next message
avatar xerces  is currently offline xerces
Messages: 11
Registered: October 2013
Go to my shop
Junior Member
I have a working java impl based on Scribe and GSON. The only difference I see is that I don't touch the headers. A cut & paste from a price req:

String url_string = BASE_URL + PRICE_URL;
OAuthRequest request = new OAuthRequest(Verb.POST, url_string);
request.addPayload(jo_req.toString());
service.signRequest(accessToken, request);

Response response = request.send();
InputStream is = response.getStream();
Re: Java API [message #98424 is a reply to message #98421 ] Thu, 11 September 2014 13:48 UTC Go to previous messageGo to next message
avatar leforthomas  is currently offline leforthomas
Messages: 17
Registered: March 2014
Go to all my models
Junior Member
Hi, thanks a lot for your reply. I tried without the headers but I get the same cryptic (and useless really...) '500 internal error'.

Given that we both use Scribe (I use v1.3.5), my only option left is the parameters being passed.

For the cart test, I have the following payload

{"modelId":1773183}

The id is correct and corresponds to one of my models.

I am on the dev server but I suppose this is not an issue.

Not sure what to try now...
Re: Java API [message #98427 is a reply to message #98424 ] Thu, 11 September 2014 14:21 UTC Go to previous messageGo to next message
avatar xerces  is currently offline xerces
Messages: 11
Registered: October 2013
Go to my shop
Junior Member
I also am using scribe 1.3.5.

I always include material and quantity in cart requests. api doc does say they are optional though.
Re: Java API [message #98434 is a reply to message #98427 ] Thu, 11 September 2014 16:55 UTC Go to previous messageGo to next message
avatar leforthomas  is currently offline leforthomas
Messages: 17
Registered: March 2014
Go to all my models
Junior Member
Nope. Thanks for your suggestion anyway.

Is there anybody from Shapeways on the forum? I wonder if it is possible to get more information than the 500 HTTP error code I get... may be it means something in itself?
Re: Java API [message #98611 is a reply to message #98434 ] Mon, 15 September 2014 17:48 UTC Go to previous messageGo to next message
avatar ProfessorBeekums  is currently offline ProfessorBeekums
Messages: 28
Registered: February 2013
Go to my shop
Junior Member
I work here
There is usually a response body that goes with the 500 error to show why there was a 500. If so, please send that over.

If there is no response body, please capture the packets with wireshark or a web proxy like Charles and attach the files.

Thanks,
Beekey
Re: Java API [message #98638 is a reply to message #98611 ] Mon, 15 September 2014 21:22 UTC Go to previous messageGo to next message
avatar leforthomas  is currently offline leforthomas
Messages: 17
Registered: March 2014
Go to all my models
Junior Member
Hi,

Thanks for helping out!

The body of the response is always null, no data.

Here is the message being sent, it's a Cart POST:

POST /orders/cart/v1 HTTP/1.1
Authorization: OAuth oauth_signature="7BKKmJiF8vlik67223M7mGSa2tY%3D", oauth_version="1.0", oauth_nonce="-108383452", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="45b191241ebd672bddf04b3fe3d5b691ed58d308 ", oauth_token="0977b73f3ee66747fa4f3333d7dafd52789b16f", oauth_timestamp="1410815847"
Accept: application/json
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.7.0_45
Host: api.shapeways.com:80
Connection: keep-alive
Content-Length: 53

{"modelId":"1773183","materialId":"6","quantity":"1 "}

[Updated on: Wed, 17 September 2014 07:31 UTC]

Re: Java API [message #98655 is a reply to message #98638 ] Tue, 16 September 2014 06:39 UTC Go to previous message
avatar leforthomas  is currently offline leforthomas
Messages: 17
Registered: March 2014
Go to all my models
Junior Member
After further investigation I realised the body wasn't empty as I initially said, there is indeed an error message being passed, and it seems the problem comes from the parameters I am passing to the API, eg "Cannot add model 1773183 , material 6 to cart" for the Cart example.
Appologies for not seing this before and thanks to all who helped out!

 
   
Previous Topic:OAuth question
Next Topic:Model Digital Preview

Logo

Hello.

We're sorry to inform you that we no longer support this browser and can't confirm that everything will work as expected. For the best Shapeways experience, please use one of the following browsers:

Click anywhere outside this window to continue.