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.

Sign up for GitHub

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

Jump to bottom

Proper GET links documentation #4

Merged
merged 1 commit into from
Jun 16, 2016
Merged

Proper GET links documentation #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 37 additions & 12 deletions api-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,66 @@

> Note: using [this markdown template](https://gist.github.com/iros/3426278).

## **List links**
## **GET links**

Retrieve a list of links ordered by creation date.

* **URL**: `?do=api[TODO]`
* **URL**: Endpoint discussion in #3.
* **Method:** `GET`
* **URL Params**
* **Path Parameters:** none
* **URL Parameters**

**Optional:**

* `offset=[numeric]`
Offset from which to start listing links (default: 0).
* `limit=[numeric]`
Number of links to retrieve (default ?) or `all`.

Number of links to retrieve (default 20) or `all`.
* `searchterm=[string]`
Search terms across all links fields.
* `searchtags=[string]`
Search for specifics tags. Tag list should be separated by a `+` delimitor.
* **Body Parameters:** none

* **Body Params:** none

* **Success Response:**
* **Content:**
* **Success Response:** `200`
**Content:**
```json
[
{
"todo": "link obj"
"id": "linkID",
"url": "Shaared URL",
"title": "link title",
"description": "link description",
"tags": [
"shaarli",
"php",
"api"
],
"private": true,
"created": "2016-06-15T19:23:14+0200",
Copy link
Member

@nodiscc nodiscc Jun 15, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm in favor of UNIX timestamps instead which do not assume the requesting machine has such or such localized date format, and are also easier to compare/work with (they are just integers).

Copy link

@mro mro Jun 15, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plz only ISO8601 acc W3C for timestamps almost as in the example, but with timezone colon: 2016-06-15T19:23:14+02:00. UTC if you prefer. Compare trivial. Nothing else plz.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does description need a (optional) mimetype nowadays (plaintext vs. markdown)? Atom/content does it this way.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is "todo"?

Copy link
Member

@virtualtam virtualtam Jun 16, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding timestamps, I've seen funny things over some APIs, where you need to multiply or divide the value of the returned Unix epoch to avoid time-travelling either to the Dark Ages™ or to the end of all known multiverses...

ISO8601 is indeed recommended for date/time representation:

@nodiscc decent programming languages propose libraries for proper date/time parsing, that developers will use when they really care about timezones and Daylight Saving Time :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does description need a (optional) mimetype nowadays (plaintext vs. markdown)?

Markdown content is also plaintext. Instead of adding an additional field, a service returning settings, included enabled plugins is probably better. It would let clients interpret any plugin if they want to.

what is "todo"?

I had to do this object definition. 😛

"updated": "not implemented yet"
},
{
<...>
}
]
```
**Notes**:
* Dates use ISO8601 format.

* **Error Response:** todo
* **Error Response:**
- `400`: Invalid parameters
Content:
```json
{ "message": "Offset should be an integer." }
```
- `401`: Invalid token/authentication.

* **Sample Call:**

```javascript
$.ajax({
url: "?do=api[??]]&offset=60&limit=20",
url: "[See #3]&offset=60&limit=30",
type : "GET",
success : function(r) {
console.log(r);
Expand Down