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
