search

tracking-exposed / eu19

2 stars 0 forks source link

documenting APIs #11

Closed berli0z closed 5 years ago

berli0z commented 5 years ago

We need to provide technical documentation for API usage, documenting the output of each one available. These is the checklist of (un-)documented APIs so far:

vecna commented 5 years ago

the metadata should not be public, it is only accessible to help debug.

the summary and CSV they should be accessible in the personal page, for this: https://github.com/tracking-exposed/facebook/issues/115

berli0z commented 5 years ago

This is a potential format for APIs:

API Docs

Before you start

Lorem ipsum dolor sit amet etc. Remember that URLs reference this values which are variables and can be obtained...

userToken: is an unique
paging: defines etc

API Index

Name Description URL
Health Check [link]() /health
Service Status [link]() /services
RSS feed [link]() /feeds/query
Personal Summary [link](#personalsummary) /personal/userToken/summary/paging
Personal Summary Extended [link]() /personal/:userToken/extended/:paging?
Personal Summary as CSV [link]() /personal/:userToken/csv/:dayrange?
Semantics [link]() /personal/:userToken/semantics/:dayrange?
Collective Stats [link]() /collective/:groupLabel/stats/:dayrange?
Collective Summary [link]() /collective/:groupLabel/download/:dayrange?

Personal Summary

URL

https://facebook.tracking.exposed/api/personal/*:userToken*/summary/:paging

Description

Returns a summary of personal data of an user based on its userToken. You can also specify paging. userToken is the token you get here, and paging defines which range of data you will retrieve.

Data Specifics

Name Description Format Example
ID ID is an unique string that represents the single impression (which can be a post or a photo appeared on a specific timeline) string 6769fd9f9ds6f0fddf
publicationTime Time in which the specific post was published. date 2019-01-01T11:41:00.000Z
bool
float64
Parameter date

Sample Usage

Request:

https://facebook.tracking.exposed/api/personal/0000f0f0f000f0000000/summary/1

Response:

```[{"_id":"0000f0f0f000f0000000","errors":[],"type":"posts","publicationTime":"1970-01-01T00:00:00.000Z","postId":"11111111111111111","permaLink":"/this.test/posts/10100100010101","author":"Test","authorLink":"https://www.facebook.com/test","texts":[],"textlength":0,"impressionTime":"2019-01-01T11:41:00.000Z","impressionOrder":1,"user":"insert-food-here","timeline":"insert-food-here"}]```
berli0z commented 5 years ago

New format here: https://github.com/tracking-exposed/eu19/blob/master/texts-wip/api.md

berli0z commented 5 years ago

APIs documentation is done. small improvements will be made as minor bugs in production are fixed.

vecna commented 5 years ago

This is good as it is!