documenting APIs

[berli0z]

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:

• Personal Summary
• Personal Stats
• Personal Csv
• Data Exporter
• Delete your Data
• General Statistics  
• Noogle
• Enrich
• semantics
• labels
• Loud
• langinfo
• languages
• keywords

[vecna]

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: tracking-exposed/facebook#115

[berli0z]

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]

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

[berli0z]

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

[vecna]

This is good as it is!