Documentation "How to start with client development"

EEXCESS / eexcess

This is the EEXCESS main repository bringing togehter the different sub-projects and providing the documentation in the Wiki. Its the starting point when you want to know more about the project.

http://eexcess.eu/

5 stars 2 forks source link

Documentation "How to start with client development" #1

Open chseifert opened 9 years ago

chseifert commented 9 years ago

When talking to potential developers of new clients, the issue of the "hidden" documentation often occurs. A client developer would need

an overview of all server calls, and
description of the api in ONE place.

Basically, this documentation could be like a white paper for developers. This issue aims at first collecting requirements and possible content. So I start with this:

Server Calls (afaik)

(required) get Recommendations
(optional) get detailed results
(optional) get favicons
(optional) entity service API
(required) user profile - request format
(required) result response format
(optional) entity service request and response format

Notation:

(required) - required knowledge for minimal client example
(optional) - for UI improvements, but not necessary for a minimal client

hziak commented 9 years ago

Shouldn't that wiki entry cover this questions, or do you think it should be explained in more detail? https://github.com/EEXCESS/eexcess/wiki/Request-and-Response-format-for-call-to-federated-recommender-and-privacy-proxy

(just seen that the favicon call is missing, i will add that now)

chseifert commented 9 years ago

I think this wiki entry is part of it. But it does not show the complete picture. How do I know that I have to look at this specifiic wiki page, or more generally, that the recommender is the central point of access? And the entitiy service api is not part of the recommender. So, I guess, it is more an overview (and link collection) page we are looking for.

Maybe an "how to start" with a simple example would be helpful, too.

mgrani commented 9 years ago

There are always two important parts of a documentation:

A step-by-step tutorial
The API.

For example AngularJS works that way (learn, develop, discuss).

ThomasCerq commented 9 years ago

The page mentioned by Hermann is related to formats. I think you should keep the description of the formats and the description of the API (calls) separate. I started to do it for the privacy proxy: https://github.com/EEXCESS/eexcess/wiki/The-Privacy-Proxy-Services. I still need to add the descriptions for getPartnerFavIcon and getPreviewImage. I agree with Christin and Michael: an overview page and a step-by-step tutorial would be useful.

Edit: My bad, Hermann. I just realised that the services are also described in the page you mentioned.

chseifert commented 8 years ago

Started it here https://github.com/EEXCESS/eexcess/wiki/Getting-Started-Guide-for-Client-Developers

URLs need to be updated to the stable versions when those are deployed

example files used: (no json upload allowed) simple-request.json.txt first-response.json.txt