Discussion: Simplified interfaces

[ajturner]

Just a start of a discussion based on initial impressions learning ArcREST.

ArcGIS has a lot of idiosyncrasies based on history, underlying implementation details and data models. This can make it confusing for a developer new to ArcGIS to interact with our system as a data management system.

For example, here is what is currently required to update the title of an item:

import arcrest
from arcresthelper import securityhandlerhelper
config = {'username': '...', 'password': '...'}
shh = securityhandlerhelper.securityhandlerhelper(config)

itemId = '...'
admin = arcrest.manageorg.Administration(securityHandler=shh.securityhandler)
item = admin.content.getItem(itemId=itemId).userItem

itemParams = arcrest.manageorg.ItemParameter()

itemParams.title = "New title"
res = item.updateItem(itemParameters=itemParams)

item = admin.content.getItem(itemId=itemId).userItem
item.title
u'New title'

Why do I need to get the userItem and then a special arcrest.manageorg.itemParameters etc. Also, these calls don't update the local item object, so it has to be fetched again from Portal. Instead could it be more resourceful:

import arcrest

config = {'username': '...', 'password': '...'}
portal = arcrest.Portal(config)
item = portal.item({id: '...'})
item.title = "New Title"
item.save
item.title
u'New title'

This could be a wrapper on top of the more bare metal classes that exist today. But likely makes more sense to new developers.

[achapkowski]

@ajturner - there are two item object in the AGOL REST API, a user item and a item. The user item is what one see when you are logged in to AGOL verse what one sees when you are not logged into AGOL. Some responses from function calls return items and others return user items, some just return the item id.

getItem() return an Item because all users can should be able to see that item regardless of ownership as long as that item is shared with that person/group/org/etc...

Part of the issue is the REST API structure, and the Python package follows that structure...

I'm all for better design and ease of use.

[ajturner]

Part of the issue is the REST API structure, and the Python package follows that structure...

This is my point. A library does not need to merely be a thin skin over the API paths. Instead it can provide a higher-level conceptual interface that obfuscates the idiosyncrasies of ArcGIS.

For example in Open Data we provide an API for dataset which can be a FeatureService Layer, ImageService Layer, TableService CSV, etc. and it definitely hides whether I own it or not. Instead there are capabilities (or subclasses) which provide specific additions while providing a common baseline.

[achapkowski]

@ajturner - I understand your point, the REST package can seem some what daunting compared to other simplified packages in Python. It's sort of like the AO of REST API where you can basically do everything.

Some of the Python package has been simplified: A good example of this is the ags sub-package where if you use the Server class inside the server.py. It basically lets you walk the server and autogenerates the service types. A user may or may not want to do this, but the option is there to use the "simpler" class vs just going directly to the service.

Do you have any suggestions for simplification?

It would probably have to be something like: arcrest_simply -> core - the full set of tools (basically what ArcREST is now) -> manage - simplified management tools -> service - easier access to services based on security method or login type? -> package - 3rd party dependencies (six.py, etc..) -> login.py - autocreates security handler based on inputs? init.py

[MikeMillerGIS]

This was sort of my idea when developing the ArcRestHelper. To build a class on top of ArcRest that provide higher level functions. As the functions I created in this class were built for solutions that needed them, the vision was never carried through. I feel ArcRest should remain as the low level interface with all the capabilities of the Rest API. Another library that abstracts this and provide common task and easier to use functions would sit on top and leverage ArcRest.

[ajturner]

@MikeMillerGIS I appreciate the preference to keep an interface in ArcRest 'pure' as a simple Python wrapper to the Portal HTTP API.

However, as you mention, I don't think that precludes using this basic library to then power a higher-level abstraction. I'm agnostic to how it's actually packaged up, but particular to what the experience is for the majority of developers.

Personally, I think the low-level library is an implementation detail that is available if a developer needs it, but that the primary interface, documentation and package presentation should be the higher-level interface.

By comparison the web is built on a 7-layer OSI model which distinctly separates several interfaces while being implementation agnostic. The vast majority of users only see the Application Layer, likely through a visual web browser or custom application. Yet enterprising developers can access the Transport (say for WebSockets) or the Network (SSL) or even Packets (GZIP, DART, etc.) What the web doesn't do is say "Here's HTML, each user can provide their own interface".

Perhaps that's a long winded-way of saying, I agree with your ArcRestHelper idea. I would recommend that is just part of ArcRest and that the capabilities are a priority need for ArcRest to be most useful across Esri and our community.

I'll also note that while I've referred several developers to use ArcRest, they've found it too difficult to start and end up writing their own simple wrappers to the API. So there is also concrete evidence that this is an unmet need and that wrapping the API is an easily solvable problem. What is hard and useful is a coherent, consistent and easy to use library interface on top of that. :)

[achapkowski]

@ajturner - with any wrapper/language/python package there is a learning curve. For a developer to just write their own wrapper, does that mean they didn't have time to learn the product, or did they not actually understand the product?

Maybe we can do a summit of ArcREST developers at UC 2016 and do a community enhancement recommendation?

[ajturner]

@achapkowski sure there is - however I would hope the learning is about the library and making it simple, not requiring someone to learn the Portal HTTP API plus the Python library nomenclature.

Purely quantitatively I'm suggesting 12 LOC to 7 LOC. now that's not entirely a fair comparison, but most developers I know are lazy, at least in RTFM. So can we make it extremely straight-forward.

Treat the API as UI. Plan on developers not reading the manual (like most users)

Maybe we can do a summit of ArcREST developers at UC 2016

How about a BoF of Python developers at DevSummit in March?

[achapkowski]

@ajturner - in progress making a facade over arcrest.

[ajturner]

Does that line up with Geosaurus?

[achapkowski]

@ajturner - yes it does

[KumarSumith]

The code works perfectly. I can get into Arcgis and pull metadata using the item. Is there any way to pull the data? Thanks for the help