subject:"Re\: V2 REST Api documentation \(first\-cut\)"

Re: V2 REST Api documentation (first-cut)

2017-03-01 Thread David Radley

Hi Apoorv,
You are welcome. I think this is very important work you are doing to 
making the documentation clear and complete, will make it easier for new 
developers to get involved with Atlas. On your responses :

1) Great
2) Great
3) Does this mean admin requests will not be documented. I would suggest 
we need to document all APIs.
4) OK I have not played with these
5) Great
6) Great. 

Something else I notice: I would have expected a PUT request for entity 
updates, as there was in the V1 API; as per the usual http verb 
definitions. Using POST for updates is not what I expected. 
  all the best, David. 

From:   Apoorv Naik <an...@hortonworks.com>
To: "dev@atlas.incubator.apache.org" <dev@atlas.incubator.apache.org>
Date:   22/02/2017 19:10
Subject:    Re: V2 REST Api documentation (first-cut)

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
>

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

Re: V2 REST Api documentation (first-cut)

2017-02-22 Thread Apoorv Naik

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
>>

Re: V2 REST Api documentation (first-cut)

2017-02-22 Thread Apoorv Naik

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
>

Re: V2 REST Api documentation (first-cut)

2017-02-21 Thread David Radley

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

Re: V2 REST Api documentation (first-cut)

2017-02-21 Thread Ernie Ostic

Thank you!  The interactive interface is an excellent way of documenting
the APIs and providing an easy-to-manage interface for prototyping,
testing, and learning the behavior of the APIs, not to mention easy
exploration of all possible "types"! We have done this with many of our
own proprietary APIs and it has proven to accelerate the learning curve and
provide something for even casual users of REST based services.  Bravo!

Ernie



Ernie Ostic

IBM Analytics

Cell: (617) 331 8238
---
Open IGC is here!

Extend the Catalog with custom objects and lineage definitions!
https://dsrealtime.wordpress.com/2015/07/29/open-igc-is-here/



From:   Apoorv Naik 
To: "dev@atlas.incubator.apache.org"

Date:   02/17/2017 10:37 PM
Subject:V2 REST Api documentation (first-cut)



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.

Re: V2 REST Api documentation (first-cut)

2017-02-19 Thread Keval Bhatt

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  in API documentation is
awesome.

Thanks,
Keval

On Sat, Feb 18, 2017 at 9:07 AM, Apoorv Naik  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.
>

Re: V2 REST Api documentation (first-cut)

Re: V2 REST Api documentation (first-cut)

Re: V2 REST Api documentation (first-cut)

Re: V2 REST Api documentation (first-cut)

Re: V2 REST Api documentation (first-cut)

Re: V2 REST Api documentation (first-cut)

6 matches

Site Navigation

Mail list logo

Footer information