Bungie-net / api

Resources for the Bungie.net API
Other
1.22k stars 92 forks source link

GetContentType, what are the available types ? #841

Open DevoidCoding opened 5 years ago

DevoidCoding commented 5 years ago

So I'm actually working on the .NET wrapper for the API and I was designing and digging in the way I'll implement it (Enum, Entities, ...) and I found nothing on the types avalaible for GetContentType in the Content namespace except "News" and "Help".

Do you have a list of those types ?

vthornheart-bng commented 5 years ago

Ah, good question! I never bothered documenting the non-Destiny parts of the API, so what little it has is all based on whatever comments we happened to write in the source code that are now being extracted.

The truth about the content types is that they're driven by configuration rather than strongly-typed enums. As a result, they're subject to change: ideally not removal unless a content type has been fully purged from the system, but definitely addition of new ones. IIRC there's an endpoint that we're not exposing publicly which will return information about all registered types. I will look into whether it'd be reasonable to start exposing that when I'm back in the office.

I should give some extra words of caution about the content portion of the system for those of you who want to use it. There are some esoteric parts of it that you'll want to be careful of.

1) There are many content types and concepts that are effectively deprecated, but have not been removed because no one has ever bothered to go through and purge the deprecated content. It could result in some confusion if you venture too far into trying to understand and support those deprecated types.

Other concepts have been deprecated-but-not-removed over time, and I'd really like to go back and clean them up but it's pretty far down the priority list: content built for old versions of the site that no longer exist is the best example. I think the content for the old Destiny 1 advertising page and the content types built to support it are still there, even though the page itself no longer exists.

2) Any "HTML" content may potentially have what I call "content item macros".

When I wrote our content management system, I had a strong desire to let people reuse content - and in doing so, to minimize the work of localizers and of stitching together pieces of content into more complex components. This effort resulted in Content Item Macros and the concept of "Content Templates". You'll see in the content that there are special identifiers inside that are frequently used, that look something like

[[ content-id="12345" template-type="direct" ]]

The content-id field points to a separate content item that you'll have to fetch in order to display the content in that location, and the template-type refers to what - for us - ended up being Javascript template files in our /scripts directory (and later, when we switched to server-side rendering, became server-side template files).

These can potentially get very complex, because I wanted it to be able to seamlessly support the idea that you might - for example - create a rotator of images, or a summary list of important news articles. In practice, however, the more advanced templates saw little use after the first couple of years, and these days they're mostly just used to embed images-as-content-items with the "direct" template type: but the templates still exist for more complex types, and still may be getting use.

3) These complex scenarios tie in with the next word of warning, which is that some content items have "set" properties that are a list of references to other content items. The most generic container for these is the "ContentSet" property, and it gets used everywhere for a variety of reasons.

Basically wherever you see a curated (as opposed to automatically sorted) list of content items on Bungie.net, they're likely being curated in a content set. Content sets made the idea of having rotators-as-templates and these other complex theoretical scenarios possible, but they can also be cumbersome to work with: particularly when you get into scenarios that have content sets nested within content sets.

4) The last word of warning I can think of off the top of my head is that content items can have "tags", and in practice we have a lot of tags that end up having special meanings. If I had it to do over again, I'd have liked to build a system, or perhaps an extension of this system, where content creators could have more control over our pages itself: but for various reasons, we ended up with pages on the site being fairly tightly locked down, and only pre-defined portions of most pages being CMS-controllable.

For instance, when you look at the homepage - the "featured" items are directly controllable, and the rest are populated outside of the CMS's control. Those portions are populated by our system looking for the most recent content item that has the given "tag" it's looking for. When I expose that endpoint I mentioned, the type information will also return various tags that it considers to be used for "important" purposes: and these "customizable locations" within the pages are what those tags equate to.