Home »  » 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 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

 
   
Previous Topic:Obtain an amount of material used for my model
Next Topic:Private models

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.