Thank you Ernie and Keval for your review (forgot to mention in prior email)
On 2/22/17, 11:10 AM, "Apoorv Naik" <an...@hortonworks.com> wrote:
>Thanks for your detailed review David.
>
>1. I see that there’s some inconsistency in the Javadocs for EntityREST fixing
>those should fix the docs too.
>2. Will update the javadocs for the *def classes too. Class -> datatype in
>javadocs
>3. I didn’t add any admin requests as I feel they’re meant for ops rather that
>devs.
>4. CRUD of enums and ObjectId is not exposed as separate API thus the docs
>don’t have any specific section for the same. The API doc examples have sample
>JSON for *def objects. Let me know if anything is missing there.
>5. Will update the javadocs for all the classes in the model package for
>better description.
>6. v2/entity/uniqueAttribute/type/{typeName} is a GET for entity so it’s under
>a correct REST resource.
>
>
>
>On 2/21/17, 5:49 AM, "David Radley" <david_rad...@uk.ibm.com> wrote:
>
>>Hi Apoorv,
>> I think documenting the API like this will make calling Atlas much more
>>intuitive; seeing the API like this for the first time makes it really
>>easy to see what there is including omissions and inconsistencies. I
>>realize you are exposing what is already there. I am not sure if this is
>>the sort of feedback you are looking for; here are my initial
>>observations:
>>
>>-v2/entity/uniqueAttribute/type/{typeName} shouldn't this be in the types
>>API?
>>- i notice the bulk APIs are in the section called "REST for single
>>entity". I suggest creating a separate section for bulk or renaming to
>>"REST for entity"
>>- "AtlasAttributeDef
>>class that captures details of a struct-attribute.
>>" I suggest class be renamed to data type. Same for other data types
>>- Some of the data types have no descriptions
>>- Are we missing the admin requests?
>>- I see we have a section on entities and classifications (Type
>>categories). It would be good to see the CRUD of enums and object_ids.
>>maps, arrays and structures somewhere in the API docs.
>>- AtlasEntityWithExtInfo Data Type is described as "An instance of an
>>entity along with extended info - like hive_table, hive_database". I think
>>these are examples not a definition of what the extended type is.
>>- AtlasEntityExtInfo has the same description as AtlasEntityExtInfo
>>- I notice that the data type attributes are not documented.
>>- I notice the JSON API is sorted alphabetically but the XML one is not.
>>- AtlasConstraintDef does not document the possible values for the
>>constraints and their usage.
>>
>>
>>If this is the type of observations you are looking for - I am willing to
>>spend more time reviewing the API,
>> all the best, David.
>>
>>
>>
>>From: Keval Bhatt <kevalbhat...@gmail.com>
>>To: dev@atlas.incubator.apache.org
>>Date: 20/02/2017 06:12
>>Subject: Re: V2 REST Api documentation (first-cut)
>>
>>
>>
>>Hi Apoorv,
>>
>>API Doc is very simplified and UI is also looks good and clear. It will be
>>really helpful to developers.
>>Integration with swagger <http://swagger.io> in API documentation is
>>awesome.
>>
>>Thanks,
>>Keval
>>
>>On Sat, Feb 18, 2017 at 9:07 AM, Apoorv Naik <an...@hortonworks.com>
>>wrote:
>>
>>> Hi Atlas community,
>>>
>>> The REST API docs (first-cut) for the new V2 endpoints and data models
>>are
>>> now available at http://atlas.incubator.apache.org/api/v2/index.html.
>>> It’d be great if we can gather some feedback on the docs, the existing
>>docs
>>> have been moved under Legacy API section now. Looking forward to the
>>> community feedback.
>>>
>>
>>
>>
>>Unless stated otherwise above:
>>IBM United Kingdom Limited - Registered in England and Wales with number
>>741598.
>>Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
>>
