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 <[email protected]>
To: [email protected]
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 <[email protected]>
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
