Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

new: draft of api concepts and usage doc #358

Merged
merged 6 commits into from Jul 9, 2019

Conversation

Projects
None yet
2 participants
@primalmotion
Copy link
Member

commented Jul 8, 2019

No description provided.

@primalmotion primalmotion requested a review from emanic Jul 8, 2019

@primalmotion primalmotion changed the title regen new: draft of api concepts and usage doc Jul 8, 2019

primalmotion added some commits Jul 8, 2019

@@ -0,0 +1,417 @@
# Aporeto API Concepts and Usage

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

Headings should be sentence case, so you can lowercase concepts and usage

@@ -0,0 +1,417 @@
# Aporeto API Concepts and Usage

Aporeto provides a ReST API to allow programmatic manipulation of all parts of the system.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/ReST/REST throughout

Everything the web client or apoctl do is done through the ReST API.

The Aporeto API accepts and returns [JSON](http://www.json.org) or [MessagePack](http://www.json.org)
encoded object.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/object/objects

encoded object.
This is controlled by the the `Accept` and `Content-Type` HTTP headers.

Most of the resources require to be authenticated and authorized:

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/to be authenticated and authorized/authentication and authorization

## Errors

When an error occurred, either due to the user input or platform error, it is returned as list of errors.
One error always has the same structure:

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/One error always has/Errors always have

- `title`: The title of the error
- `description`: A more detailed description of the error
- `code`: The status code of the error
- `trace`: Eventual trace ID that can help Aporeto engineers to trace the cause of the error.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/Eventual trace/Trace

This comment has been minimized.

Copy link
@primalmotion

primalmotion Jul 9, 2019

Author Member

well ok, but it's really there eventually :)

- `204 No content`: The request is a success and there is no additional body.
- `400 Bad Request`: The data of your request is invalid or incomplete.
- `401 Unauthorized`: You are not correctly authenticated.
- `403 Forbidden`: You are authenticated, but you do not have sufficient permissions.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/you do not have sufficient permissions/are not authorized

- `400 Bad Request`: The data of your request is invalid or incomplete.
- `401 Unauthorized`: You are not correctly authenticated.
- `403 Forbidden`: You are authenticated, but you do not have sufficient permissions.
- `415 Usupported Media Type`: Invalid `Content-Type` or `Accept` HTTP Header.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/Usupported/Unsupported
Also:
s/Header/header

- `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout`: Temporary communication failure.

> There may be additional error codes in certain circumstances.
> Please refer to the HTTP error code documentation for more information.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

We offer several note styles now in junon...for this I would suggest perhaps a "note" style...so you can do this:

:::note
<your text>
:::

Also, we should hyperlink them to just where they can find this "HTTP error code documentation"

This comment has been minimized.

Copy link
@primalmotion

primalmotion Jul 9, 2019

Author Member

this is not markdown compliant and would render weird on github.

```

The token is a [JSON Web Token (JWT)](https://jwt.io) that can be exchanged from one of the supported authentication
source:

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/source/sources

- Aporeto account: username and password.
- App credentials: X.509 certificate.
- User configured OIDC provider.
- User configured LDAP server.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

What about the Kubernetes authentication mechanisms, do we support those? Perhaps this topic must be deferred for now but it could be interesting to include if possible as I imagine they could potentially access our API through the Kubernetes master and use its authentication mechanisms? I am not sure. cc @mheese

This comment has been minimized.

Copy link
@primalmotion

primalmotion Jul 9, 2019

Author Member

no we don't. They need an appcred to do so.

Regardless of the realm, Aporeto will validate the user provided info and will convert identification
bits into claims that are inserted in the JWT.

Administrators can then write API authorization policies based on these claims to authorize actions

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/API authorization policies/API authorizations

- `AWSIdentityDocument`: This realm is deprecated.

The `validity` property controls how long the token will be valid.
It is expressed in a simple duration format, like `10s`, `6h` or `24h`.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

I think that it can be good to specify that it is a Golang duration...as this datatype is unique to Go and not everyone is using Go.


The `metadata` attribute contains various realm-dependent information (see below).

Upon correct authentication, Aporeto will return a JWT wrapped into a JSON or MessagePack object:

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/into a/in a

```

The `token` attribute contains the actual JWT you need to pass into the `Authorization` HTTP header for every
subsequent requests.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/requests/request

}'
```

### Authenticating with a X.509 Certificate

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/Certificate/certificate

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

Also:
s/a/an
(throughout...see lines 153, 155)


### Authenticating with a X.509 Certificate

> How to retrieve a X.509 certificate from Aporeto is not in the scope of this document.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

^^this can also be a note style


Most of the resources in Aporeto live in a namespace.
When you issue a command, in addition to your JWT, you must pass the `X-Namespace` HTTP header.
This will tell the system which namespace the request is targeting and what API authorization policy to apply.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/API authorization policy/API authorization

When you issue a command, in addition to your JWT, you must pass the `X-Namespace` HTTP header.
This will tell the system which namespace the request is targeting and what API authorization policy to apply.

Note that the API authorization associated to your JWT claims will depends on the namespace you target.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/to/with
s/depends/depend


## Idempotency

The Aporeto API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for `POST` operations.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

Even though I personally think Wikipedia is a good source of information and I know many people rely on it and it does a great job, I am not sure we can consider it authoritative, particularly in the context of technical documentation. It's generally better to link to a more proper source, such as a spec. In this case, I think this link could be a better choice https://tools.ietf.org/html/rfc7231#section-4.2.2

This comment has been minimized.

Copy link
@primalmotion

primalmotion Jul 9, 2019

Author Member

well I was really pointing to general concept of idempotency, not its application in our context.

## Idempotency

The Aporeto API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for `POST` operations.
This allows to safely retry requests that returned a communication error, but actually was honored by the system.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/allows to/allows you to


The idempotency key is passed through the HTTP header `Idempotency-Key`.
The value needs to be a unique identifier.
[UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) are generally widely used.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

Similarly, it will probably be much better to link to an RFC or more authoritative source. For this situation, I located https://tools.ietf.org/html/rfc4122 which could work here.


### Hierarchy layout

The Aporeto API follows a 3-level structure to traverse the hierarchy.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/3/three


The Aporeto API follows a 3-level structure to traverse the hierarchy.
For instance, for an hypothetical object `parent` that can have `children` who can in turn
have `grandchildren`, Aporeto layouts the API URLs as follow:

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/layouts/lays out
s/follow/follows


- `/parents`: Affects all parents.
- `/parents/:id`: Affects a particular parent with the given ID.
- `/parents/:id/children`: Affects a all children in parent with the given ID.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/a all/all

- `/parents/:id`: Affects a particular parent with the given ID.
- `/parents/:id/children`: Affects a all children in parent with the given ID.
- `/children`: Affects all children
- `/children/:id`: Affects a particular children with the given ID.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/children/child
(children can not be singular)

@emanic
Copy link
Contributor

left a comment

Great information! Thanks for putting this together! 💯

- `/parents/:id/children`: Affects a all children in parent with the given ID.
- `/children`: Affects all children
- `/children/:id`: Affects a particular children with the given ID.
- `/children/:id/grandchildren`: Affects a all grand children in child with the given ID.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/a all/all
s/grand children/grandchildren


### Methods

Aporeto API uses standard HTTP methods to perform actions on resources.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/Aporeto API/The Aporeto API

### Methods

Aporeto API uses standard HTTP methods to perform actions on resources.
Not all methods apply to all URL.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

s/URL/URLs

change. This will ensure (especially through the `updateTime` property) there is not conflicts
in the case two clients are updating the same resource at the same time.

> NOTE: `PATCH` method support will be available later.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

Here is an example of documenting "future features" which we want to avoid. Unfortunately, the future is unknown so it is better not to make promises (especially in technical documentation). So it will be better to delete line 363.


The `DELETE` method can only be used with the following resource URLs:

- `PUT /parents/:id`: Deletes the parent with the given ID.

This comment has been minimized.

Copy link
@emanic

emanic Jul 8, 2019

Contributor

I do not know if this is an error but when I read about DELETE I expect to see DELETE but here I see PUT. Very confusing! hopefully this is just a typo

This comment has been minimized.

Copy link
@primalmotion

primalmotion Jul 9, 2019

Author Member

it is indeed

@primalmotion

This comment has been minimized.

Copy link
Member Author

commented Jul 9, 2019

/build

@primalmotion primalmotion merged commit 718bd95 into master Jul 9, 2019

2 checks passed

built
Details
unit-tests
Details

@primalmotion primalmotion deleted the api-concepts branch Jul 9, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.