Pretty much all types that return a collection should be refactored to return a Relay Connection so that we can handle pagination in the future without breaking stuff. Furthermore, we might want to review GitHub's GraphQL API since they seem to extend the idea of Relay Connections:

{
  securityVulnerabilities(first: 5) {
    totalCount
    edges {
      __typename
      cursor
      node {
        advisory {
          id
        }
      }
    }
    nodes {
      advisory {
        id
      }
    }
  }
}

Basically, every collection in the GraphQL API returns the following:

• totalCount: the total number of items in the collection
• edges: the typical Relay Connection type w/ cursors and stuff
• nodes: a helper that returns the same thing as edges but w/o cursors (if you don't have a need for pagination)

More specifically, we still use legacy collections in these locations:

• api.serlo.org/src/graphql/schema/uuid/taxonomy-term/types.graphql

  Line 25 in 119aad2

  children: [AbstractUuid!]!

• api.serlo.org/src/graphql/schema/uuid/user/types.graphql

  Line 12 in 119aad2

  activeDonors: [User!]!

• api.serlo.org/src/graphql/schema/uuid/abstract-taxonomy-term-child/types.graphql

  Line 10 in 119aad2

  taxonomyTerms: [TaxonomyTerm!]!

• api.serlo.org/src/graphql/schema/uuid/abstract-navigation-child/types.graphql

  Line 7 in 119aad2

  path: [NavigationNode!]!

The option bypassCache in SerloDataSource is not needed anymore.

Currently, we add the discriminator each time in set* in SerloDataSource. Instead, we should just add them to the server response instead so that we can get rid of the custom behavior.

{
  uuid(id: 57201) {
    __typename
    ... on GroupedExercise {
      currentRevision {
        id
        content
      }
    }
  }
}

still returns the previous revision, although a new revision was checked out a couple of days ago.

Currently, we can't differentiate Sentry issues by env. We should add that somehow (e.g. via env variable or something).

serlo/frontend#95

Version should be without api.serlo.org prefix.

E.g.

{
  uuid(id:1855) {
    ...on Article {
      taxonomyTerms {
        navigation {
          data
        }
      }
    }
  }
}

Idea: services communicate which cache keys they can have so that we can use the information to fill the cache beforehand.

Basically, the GraphQL types should look like this:

extend type Query {
  _getCacheKeys(
    after: String
    before: String
    first: Int
    last: Int
  ): Query_GetCacheResult!
}

type Query_GetCacheResult {
  edges: [CacheKeyCursor!]!
  nodes: [String!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

type CacheKeyCursor {
  cursor: String!
  node: String!
}

See src/graphql/schema/notification for an example on how to work with connections.

Furthermore, we need a legacy API endpoint that returns the cache keys for serlo.org:

• GET /api/cache-keys returns an array of strings (i.e. the cache keys). This request won't be instance-aware, so it should return cache keys from all instances.

Checklist

• Add _getCacheKeys to src/graphql/schema/cache.
• Add contract test for _getCacheKeys that uses /api/cache-keys.

See serlo/serlo.org-legacy#474. Zend sometimes serializes arrays as objects (i.e. Record<number, unknown>). We should be able to handle those in payloads everywhere (we already handle this somewhere for notifications) since we apparently can't configure Zend to serialize stuff correctly w/o writing our own serializer...

{
  uuid(alias:{ instance:de, path: "/mathe/zahlen-größen/prozent--zinsrechnung/prozent"}) {
    id
    __typename
    ... on Article {
      taxonomyTerms {
        id
        navigation {
          data
        }
      }
    }
  }
}

doesn't work in staging (vs. production)

Currently, all GraphQL mutations failures are grouped together. We should at least add the operation name to Sentry so that we can differentiate different GraphQL mutation failures.

As a consumer of the API (e.g. frontend), it would be helpful to have access to the TypeScript types (that we mostly already have). Need to make sure, that:

• Names are consistent.
• The types actually match the return type (i.e. especially check that the subtypes are correct).
  Also:
• CI that releases @serlo/api with same version number as the docker image.
• Possibly include Edtr.io TypeScript tooling to easier check for breaking changes in the API.

See #14.

Probably create an interface for that (AbstractExercise) that will be implemented by GroupedExercise & Exercise.

Similarly to https://github.com/serlo/api.serlo.org/blob/master/src/graphql/schema/notification/resolvers.ts#L77, we need a mutation

mutation setUuidState(id: Int!, trashed: Boolean!): AbstractUuid

that sets the trashed property of the corresponding uuid.

• Add mutation setUuidState (probably to https://github.com/serlo/api.serlo.org/blob/master/src/graphql/schema/uuid/abstract-uuid/resolvers.ts).
• Add unit tests for setUuidState.
• Add contract test for setUuidState (see https://github.com/serlo/api.serlo.org/blob/master/__tests-pacts__/serlo.org/set-notification-state.ts).

Status

• Queries are done 🎉
• Mutations are tracked here: #111 and #177

We want to add threads to the uuid type. So no additional root query necessary. Something like:

{
  uuid(id: 1855) {
    threads {
      totalCount
      nodes {
        id
        createdAt
        updatedAt
        title
        archived
        trashed
        object # Back link to the uuid the thread is tied to
        comments {
          totalCount
          nodes {
            id
            content
            createdAt
            updatedAt
            author
          }
        }
      }
    }
  }
}

Furthermore, we need mutations for various types of actions:

mutation createThread(
  # ...
}
# createComment
# archiveThread
# ...

Required legacy API endpoints

• GET /api/threads/:object-id returns all the threads for the object with the given id (with thread ids only)
• GET /api/thread/:id returns the thread with the given id (including its comments)
• POST /api/create-thread creates a thread
• ...

• uuid should be able to resolve /:id to the specific uuid.
• User's alias should be /user/profile/:username.
• uuid should be able to resolve /user/profile/:id to the specific user.
• uuid should be abe to resolve /user/profile/:username to the specific user (might need a mapping from username to id).

Second part of #41.

We need a mutation

mutation _updateCache(keys: [String!]!)

that tells the API to update the cache of the given keys. To achieve this, we need to map the cache key to the corresponding data source (i.e. *.serlo.org* maps to SerloDataSource, spreadsheet-* maps to GoogleSheetApi) and then tells it to update the cache (i.e. executing the corresponding get method without returning early when the cache is already set).

• Add mutation _updateCache.
• Add unit test for *.serlo.org* cacheKey.
• Add unit test for spreadsheet-* cacheKey.

Approach for extending the API:

• Add contract tests that define newly needed endpoints
• Implement the GraphQL resolvers
• Publish contract tests and add the new endpoints to https://github.com/serlo/serlo.org

Things to consider:

• The new endpoints in https://github.com/serlo/serlo.org should be prefixed with /api (e.g. /api/license/<id>. Prefer GET requests where possible (i.e. prefer URL parameters over POST body)
• Limit the required requests (e.g. fetch nested data that requires new requests only if it is requested)

Next Priorities:

• API for https://de.serlo.org/mathe (pages)
• API for https://de.serlo.org/mathe/zahlen-gr%C3%B6%C3%9Fen/prozent--zinsrechnung/aufgaben-prozentdarstellung (topic-folder)
• API for https://de.serlo.org/mathe/zahlen-gr%C3%B6%C3%9Fen/prozent--zinsrechnung (subject / topic)

Status:

• Uuid
  • Entity
    • Article
    • ... other entity types
  • EntityRevision
    • ArticleRevision
    • ... other entity revision types
  • Page
  • PageRevision (serlo/cloudflare-worker#8)
  • TaxonomyTerm (https://github.com/serlo/serlo.org-cloudflare-worker/issues/9)
  • User
  • ... other uuid discriminators
• License
• ... other

We should rewrite the queries in tests/schema/uuid/abstract-navigation-child.ts using GraphQL variables so that autoformatting & IntelliSense works for them, too.

Example query using GraphQL variables:

Currently, https://api.serlo.org/___graphql goes through the Cloudflare Worker anyways, so there is no need for a specific playground service token. We could remove that and let the local playground use the (mocked) Cloudflare Worker secret instead.

Similarly to AbstractTaxonomyTermChild, a common AbstractNavigationChild interface would make our current tests easier.

See comments in #25.

Would be nice if we can add some documentation to the GraphQL schema since the nomenclature in serlo.org is not always obvious :)

• Query _getCacheKeys that returns a connection of strings that should be cached (#42).
• Mutation _updateCache(keys: [String!]!) that tells api.serlo.org to update the cache of the corresponding keys (#51).
• Docker image that uses _getCacheKeys and _updateCache to update/fill the cache.

Changes to the navigation aren't reflected in the cache, yet.

See comments in #35.

See #14.

We allow special characters to be part of the url. We should probably url-encode these at the API level.

For each type, we have a _set* mutation that allows serlo.org to set the cache. This is kind of annoying to maintain. Moreover, the GraphQL typing doesn't help us in this place, anyways. So we should just get rid of it and combine a setCache mutation that acceps the key and the value.

• Run contract tests on push / pull_request
• Publish contracts on push to master

steps:

• http://localhost:3000/___graphql
• build query with user id that is not trashed and has a description
• query:

{
  uuid(id: 18981) {
    __typename
    id
    ... on User {
			trashed
			username
      description
    }
  }
}

results in

{
  "data": {
    "uuid": {
      "__typename": "User",
      "id": 18981,
      "trashed": false,
      "username": "wolfgang",
      "description": "NULL"
    }
  }
}

Basically: move the logic from https://github.com/serlo/frontend/blob/9f0fcd74be4cedf0bd07d213c23f28e4f79071d1/src/events/event.ts into the API, resolving ids to their corresponding data structure.

Maybe: add worker that we can run nightly that sets / updates the cache for every (relevant) entity?

POST requests (e.g. /api/set-notification-state) should also have a contract test.

IMHO, the documentation directly offered by GraphQL wasn't really helpful (see #7 and its implementation):

• It made the code base less readable because of comments above every field.
• We couldn't really document stuff that is not obvious from the names already (e.g. a seemingly arbitrary JSON-String).

Instead, we should add a human-created documentation that can also explain high-level stuff, e.g.:

• a GitHub wiki in this repository
• a statically generated site deployed via Vercel on docs.api.serlo.org
• a docs site expanding projects on serlo.dev / docs.serlo.org that we can use in the future for other projects (currently it would be nice for content API & API). Might also be a nice place for changelogs etc.

Needs some thinking before implementing. Basically we have two use cases:

• When accessing an entity/page over uuid, we want to be able to access the taxonomy path to that entity/page for the breadcrumbs
• We want to be able to access taxonomy uuids over uuid

Probably implement that similar to currentRevision:

• Add taxonomy stuff to uuid
• When accessing an entity/page over uuid and requesting taxonomyParent (name tbd), do sub-requests to uuid if needed. Something like

{
  uuid(id: 1855) {
    ... on Article {
      taxonomyPath: { # List of taxonomy elements, probably has sub types
        id
        title
      }
    }
  }
}

At the moment, the data sources classes share only the super class RestDataSource without any super class and/or interface that is app specific. When the data sources scale we may have maintainability problems. Besides that, it can lead to verbose code when we have to use such classes in the same logic (v.g. resolver for updateCache, see #57 ).
CacheableDataSource would be a good name for super class/interface here.

There are some unresolved / wrong peerDependencies. Although those doesn't seem to cause errors in the running, we should fix them were possible.

We want to expose the notifications of the currently authenticated user via our API. Since every notification has an event associated with it, this basically needs two components:

• Expose the notifications.
• Expose the events (This is the tricky part since there are a couple of different event types with different payloads).

In the end, we should have a notifications query of the following form:

{
  notifications() { # We might add filters at a later point
    totalCount      # The total number of notifications. Probably fixed at around ~20 right now in the legacy system
    nodes {         # The actual list of notifications
      id            # ID of the notifcation. We probably want to expose that as a string to be compatible with what we want to achieve in the future
      unread        # True iff the notification has not been read by the user.
      event {       # The event that triggered the notification.
        id          # ID of the event. Again, a string.
        type        # Type of the event. See a list of available types below.
        instance    # The instance the event has been triggered in.
        date        # Datetime the event has been created.
        actor {     # The user that triggered the event.
          # User subtype
        }
        object {    # The object that the event has been triggered on.
          # Uuid subtype
        }
        payload     # Arbitrary JSON-String containing additional information about the event. We should document that somewhere (per event type). 
      }
    }
  }
}

Furthermore, there should be a way to mark notifications as unread/read.

mutation setNotificationState(
  id     # The ID of the notification which read status should be changed.
  unread # The value the unread state should be set to.
)

Note: Both query and mutation are tied to the currently authenticated user. So they need to work with the user token.

Reference

Event types

These are all the event types that we currently support in the legacy system. We might want to rename that on the API level so that we have a consistent naming scheme in the future.

discussion/comment/archive
discussion/comment/create
discussion/create
discussion/restore
entity/create
entity/link/create
entity/link/remove
entity/revision/add
entity/revision/checkout
entity/revision/reject
license/object/set
taxonomy/term/associate
taxonomy/term/create
taxonomy/term/dissociate
taxonomy/term/parent/change
taxonomy/term/update
uuid/restore
uuid/trash

Required legacy API endpoints

• GET /api/notifcations/:user-id returns all the notifications for the user with the given id (with event id only)
• GET /api/event/:id returns the event with the given id
• POST /api/set-notification-state/:id sets the unread state for the notification of the given id

Observing a couple of 413 that is probably the API server. We should increase the maximum request body size (at least for services like serlo.org since the legacy API requests may be quite large).

To check which entities the current user is subscribed to. An example query would be:

{
  subscriptions(first: 5) {   # Returns a connection of Uuids
    totalCount
    nodes {
      __typename
      id
    }
  }
}

Basic approach:

• Add subscriptions query in src/graphql/schema/subscriptions (user-specific, so similarly to src/graphql/schema/notifications)
• Add unit tests for subscriptions that mocks the legacy endpoint GET /api/subscriptions/:user-id (that should return a list of ids)
• Add contract test for subscriptions that uses the legacy endpoint GET /api/subscriptions/:user-id (similarly to _cacheKeys)

Third part of #41.

Basically:

• We need a function that uses _cacheKeys and _updateCache to fill/update the whole cache:
  • Probably fine to create a new file src/worker.ts for that (independent of the current server) for now. Might refactor the repo into a monorepo. Will see.
  • Accepts the API endpoint as a function argument (and possibly the service name + secret for the token)
  • Uses graphql-request to do the requests. Probably something like:
    • Fetch the next 10 keys using _cacheKeys , update those keys using _updateCache, continue until no cache keys left.
    • Shouldn't fail if updating a single cache key fails for some reason.
  • Can probably be unit tested.
• After that: create a Docker image that executes src/worker.ts (using the provided environment variables for arguments). As noted above: we might want to refactor this repo into a monorepo for that since the worker will have different dependencies compared to the server.
  • @inyono Also add to CI and stuff.

See serlo/frontend#420 (comment). Might be the case for other types, too. Should also check the behavior of sub resolvers (and potentially change the type if we need to cover null).