atlas-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apoorv Naik <an...@hortonworks.com>
Subject Re: V2 REST Api documentation (first-cut)
Date Wed, 22 Feb 2017 19:10:09 GMT
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_radley@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 <kevalbhatt18@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 <anaik@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
>
Mime
View raw message