The AutoCAD I/O team has deployed version 2 of their API. For specific information on what’s new, check this page. As I’ll be talking about AutoCAD I/O at AU 2015, I thought it important to get to grips with the new version and understand how it differs from v1.
I went ahead and updated Jigsawify.com to make use of the new API, so I’ll add my own commentary below on the changes that have been introduced. As a reminder, the full source code for Jigsawify.com is available on GitHub.
To check out the specific migration changes, see this comparison of the two branches. Bear in mind that the v2 branch now also contains the “management” app that allows you to create, delete and update a custom AppPackage and its corresponding Activity (it was originally based on this sample but I upgraded it for the v2 API). So in the diff you’ll see lots of additional files that don’t have an equivalent in the v1 branch.
(To create my v2 management app I followed this tutorial and copied/migrated code from the original sample.)
Anyway, onto the changes themselves… I’ll start with the ones I encountered in my migration, and then comment on others I find significant.
The service end-point has changed
From:
https://developer.api.autodesk.com/autocad.io/v1/
to:
https://developer.api.autodesk.com/autocad.io/us-east/v2/
I like that the location has become explicit, which raises the possibility of eventually being able to choose a data centre in Europe (should it make sense).
OData 4.0
I had to make a few changes to the data being passed using OData. Most of these are abstracted away in the management app code – as we’re using an OData Client to do lots of the low-level stuff – but in the Node.js code on the server it’s a little more obvious. You’ll see the specifics in the delta for the “api.js” file in the comparison linked to previously.
Removed EntityId
There is no longer a UserId associated with AppPackages, Activities and WorkItems.
This is a welcome change: in my code I’d previously had to filter on the UserId of WorkItems, etc., which didn’t feel right (the code ended up included a user-specific ID, making it much less portable).
Something related to this change: because there’s now more risk of Activity names clashing, we do recommend prefixing them with a Registered Developer Symbol (RDS). Although as this facility seems now to have been retired, so I’m not sure how you’re meant to proceed if you don’t have one. I’d certainly recommend using something suitably obscure for the name. Oh, and you can’t use a full stop/period as a delimiter – I found you have to use a hyphen (-) or an underscore (_) to avoid an exception.
Use Http Get for AppPackage's Upload URL
You’d previously have to use code (in this case it’s in C#) such as this to determine the URL where you can upload your AppPackage:
UriBuilder builder = new UriBuilder(container.BaseUri);
builder.Path += "AppPackages/GenerateUploadUrl";
var url = container.Execute<string>(builder.Uri, "POST", true, null).First();
Now life is much simpler: you can use a GET request instead, e.g.:
var url = container.AppPackages.GetUploadUrl().GetValue();
Of course there’s some abstraction happening behind the above code – they are being mapped to lower level HTTP calls – but you get the idea.
No AddLink/DeleteLink Call Anymore
This simplifies your code slightly. Where previously I used this:
container.AddToActivities(activity);
container.SaveChanges(
System.Data.Services.Client.SaveChangesOptions.PatchOnUpdate
);
container.AddLink(activity, "AppPackages", package);
container.SaveChanges();
I now just do this:
activity.AppPackages.Add(PackageName);
container.AddToActivities(activity);
container.SaveChanges();
I assume this simplification comes from no longer having “complex” EntityIds for AppPackages and Activities.
Now for the updates that didn’t impact me directly…
Added Engines EntitySet
This seems like it could be useful, especially when working with different “AutoCAD” versions. (I used quotes because we’re talking about Core Engine versions, although these will tend to correspond closely with full AutoCAD versions.)
Versioning Support
Again, seems useful: I often have to roll-back to prior versions, so this will be helpful.
New Description property on Activity/AppPackage/Engine
This will be useful when I start sharing Activities with others.
New Headers property on Argument
I don’t currently use my own cloud storage mechanism for the site, but I can see how this would become useful if I did.
New "IsPublic" property on Activity/AppPackage/Engine
Yes, at some point I’ll end up publishing Activities to others… is there anyone else out there wanting to use AutoCAD I/O to create jigsaw puzzles? :-)
New “HostApplication” property on Activity
Interestingly, the infrastructure has now been generalised to the point you can specify an alternative executable to AcCoreConsole.exe – you can choose to use a custom host application. It’ll still be beholden to the same sandboxing as we use for the core engine, of course, but this is potentially really interesting, especially if you know that a RealDWG app can meet your needs (as it’ll have even lower execution overhead).
New “IsObjectEnabler” property on AppPackage
Allows you to tag AppPackages as Object Enablers and have them load on startup. Interesting if you’re implementing them.
Added Optional property on Parameter in Activity
While I haven’t yet used this, I have wanted it in the past… I would probably have made slightly different architectural decisions had the option been there. Something I’ll use in the future, for sure.
That’s it for this quick run-through on the migration work I personally found needed with the new AutoCAD I/O v2 API. Overall the changes make sense – it’s certainly allowed me to clean up quite a bit of my code. If you’re using v1 of the API, I recommend taking the time to migrate to v2. It’s not a very big deal, and will certainly bring longer-term benefits.
I’m jumping on a plane bound for San Francisco, tomorrow, to present at next week’s Autodesk X-Summit. I’ll also be spending a few days in the San Francisco and San Rafael offices, after that. I’ll certainly be reporting what I can via this blog, as usual.