To what extent are we consistent w/ the python API?

[tomwayson]

While it would be nice to mirror the Hub.py API, Python and JS are different languages, used in different contexts. For JS that runs in a browser, there is a real cost to adding bits that don't get used (like CRUD operations that won't get used in a read-only site), and potential memory leaks left around by objects that aren't destroyed. In those scenarios it's preferable to compose your application out of dependencies that expose stateless functions - like https://github.com/Esri/arcgis-rest-js/

If we need to mirror the Hub.py API, then maybe we just add a top level package to this repo that consumes the the libraries that expose stateless functions and exposes a hateful stateful API (const hub = new Hub(myCommunityOrgUrl)) that does all the things.

[jgravois]

i'm gonna go out on a limb and say no one is going to jump back and forth between using both of these libs extensively.

if i'm wrong and a developer does use both, i think they'd actually appreciate the fact that the architecture of each library deviates in order to take advantage of the strengths of each language and that we've crafted each project using hard-fought wisdom.

that said, at a level higher up, i think we should allocate time to document the surface area of each using a matrix to get them aligned with regard to parity in capabilities. if developers can navigate helpful examples that demonstrate that the puzzle pieces fit neatly together to execute common tasks, they'll consider the two libs consistent.

[tomwayson]

Good point @jgravois - we will be at least functionally equivalent, and if there's a need to be syntactically equivalent then I suggest my idea above of adding a package that wraps the functional APIs in the other packages.

To that end, from https://github.com/esridc/hub-py/wiki/Implemented-methods-and-its-usage here's what Hub.py currently does:

Functionality	Hub.py API	Proposed Hub.js API	Issue/PR
Fetch all org initiative items	myHub.initiatives()	arcgisHub.fetchOrgInitiatives(orgId)
Fetch all org initiative names	myHub.initiative_names()	just use fetchOrgInitiatives()
Fetch all org initiative ids	myHub.initiative_ids()	just use fetchOrgInitiatives()
Fetch initiative description	myHub.initiative_descriptions()	arcgisHub.fetchInitiative(initiativeId)	#8
Search org initiatives	myHub.initiative_search(name=None, created=None, modified=None, tags=None)	arcgisHub.searchInitiatives({ org: orgId, title, created, modified, tags })
Fetch all org event items	myHub.events()	arcgisHub.fetchOrgEvents(eventServiceUrl)
Fetch all org event names	myHub.event_names()	just use fetchOrgEvents()
Fetch event description	myHub.event_description(name=None)	arcgisHub.fetchEvent(eventServiceUrl, eventId)
Fetch events for an initiative	myHub.events_for_initiative(name)	arcgisHub.fetchInitiativeEvents(eventServiceUrl, initiativeId)
Search org events	myHub.event_search(name=None, location=None)	arcgisHub.searchEvents(eventServiceUrl, { title, location, date })

The main difference is that so far all the python functions are implicitly scoped to an organization b/c they hang off myHub. You can start to see the wisdom of that once you look at the event APIs, where you need to get the url of the event feature service for the org for each call. That means there are additional implicit APIs like getEventServiceUrl(orgId).

[ajturner]

Spot on - the goals is to have capability parity and coherence. Both should be -ic (pythonic, js-ic), but consistent naming of parameters, defaults, methods when possible.

Specific to the JS methods - can we use getInitiative instead of fetch? And drop the Org which seems unnecessary, confusing (what’s an Org?) and potentially limiting (search for initiatives across any org)

We will also need to support Create, Edit, Delete on things. This will be a priority for Urban. Create new initiative or Create initiative from template.

I’m not sure if anyone in JS uses an IDE, but if we want Useful autocomplete, we should consider using the thing type, then operation e.g.:

• initiativeGet( { id: .. } )
• initiativeEdit( { id: .. } )
• initiativeCreate( { id: .. } )
• initiativeDelete( { id: .. } )

[jgravois]

JavaS-cryptic

[tomwayson]

can we use getInitiative instead of fetch?

We just settled on using 'fetch' as a prefix b/c it's more descriptive of what it's going to do - implies async, etc. However that is inconsistent w/ Hub.py and arcgis-rest-js, so maybe going back to 'get' is better.

And drop the Org which seems unnecessary, confusing (what’s an Org?) and potentially limiting (search for initiatives across any org)

That only exists for parity w/ Hub.py, which is always scoped by Org, and is really just a convenience wrapper around searchInitiatives({org: orgId}). So let's start w/ that and if we need the convenience fn later, we can add it.

We will also need to support Create, Edit, Delete on things. This will be a priority for Urban. Create new initiative or Create initiative from template.

For most Hub entities (initiatives, sites, pages, events, etc) we'll need to handle this via a new Hub REST API. Once that is in place, this library can include calls to those end points.