Ultimate Contentful API, SDK and App Guide For Beginners!

one of the harder parts of mastering any new CMS is trying to figure out how to get the data out of the CMS and render it onto our web page or an app or whatever now if you decided to use content for as your CMS of choice you may have noticed quite quickly that you have a plethora of ways to access the data in the CMS so out of the box contentful ships with a Content delivery API an Administration API a user management API a graphql layer for officially supported npm packages eight sdks as well as a handy few Marketplace apps that you can make use of so what I thought it might be useful to do in this video is give you a bird's eye view on what you need to know in order to master data access within contentful now in this video you will learn what bits of data you need to successfully communicate with contentful and how to generate these within the CMS I'm also going to cover some of the Hidden gotchas that can easily catch you out on a project and make you miss that ever increasing deadline now these are the things that can cause you hours of head scratching at first however once you master will make complete sense now the first API that we're going to cover is a classic and it's called the smash on the Subscribe button API and help me out with that pesky YouTube algorithm by clicking on like now if you haven't come across this channel before my name is John and I release a new video every Sunday that will help you build Enterprise grade websites and make you a Bonafide coding Legend So if you haven't already you know what to do now if the reason why you've come to this video is to learn more about contentful then it's worth pointing out I've written a book all about contentful which covers everything that you need to know from setup installation all of that good stuff and it's called content for the missing manual now you can buy this book from lean Pub which is linked to below it's only 15 bucks and it will give you everything you need to be successful with contentful now let's go back to the content foreign you're going to need to know how to access three specific bits of data so what we're going to do now is log into the CMS and see how we can generate each one in turn so the first bit of data is called the space ID and this is related to the organization and the space that you want to query so in content 4 you can see that it's possible for me to create multiple spaces now in terms of my space ID you'll be able to find it directly within the URL so hopefully you can see this here this value here the next bit of data you'll need is the environment ID so you can kind of think about environments just like branches within git so it's possible to create a branch off the master Branch so then different content editors or developers can work in isolation without impacting the main website now in order to create a new environment within the top and then go to the settings option bomb here you'll be able to see this environments tab by default every single contentful space will be created with the master Branch now it is possible to create a different one say let's call it development and then these IDs here are the IDS that you'll need to reference within your code in order to access it now the final piece of the puzzle is an access key you're going to need a way to actually validate that you're the right person and you can access content from the CMS anyone any Tom Dick or Harry accessing your secure content now in order to create an access token or get access to it again you can go to the settings tab from here we can go to API Keys now in API Keys you'll see that we've got the content delivery pre-preview tokens so what we want to do is click on the big add API key and then from here we're going to give it a name so let's just call it website access you can see that we've got our space ID here and then we've got access to our content delivery access token and our preview access token so when we're creating our code making rest API or using the SDK we're going to need this access token now a lot of people will say when I'm looking at my content how do I make sure that content editors can see normal content and preview content this is dead simple all we need to do is send the different API token so because we have one for the main Master content and we have one for preview in order to create a preview mode all you need to do is set something up like an environment variable and then pass the preview access token back to CMS rather than the main content delivery API access token and then you get returned preview content so this is really nice because it means you don't have to write additional code it's just basically switching that access code when the website starts up or app and everything is taken care of for you and basically these are the only three things that you need in order to be able to make requests from content form now that you have that access token space ID and the environment name you pretty much have all the data you need in order to use any API or SDK with contentful so let's see how we can map this into a specific request now in order to access contentful you can either use the API or an SDK and if I'm honest all the sdks really do is wrap calls to the API so if you can Master the API you can Master these sdks really easily now on the screen you can see my Postman and in order to access the content delivery API you will be accessing the cdn.contentfull.com now in this example we're going to then access a space so we need to put spaces then using that space ID that we looked at we passed that into the URL then we do environments then using that environment identifier that we mastered then we add that in then after that you put in the endpoint you want to query in this specific example I'm querying the entries endpoint and I want to query content full for a single bit of content to keep this video precise in this example we're just going to focus on the get entry endpoint however it's worth noting that the content deliver API can also do things like get assets get spaces and all that sort of good stuff as well so in order to do this I just do entries and then at the end I put in the identifier for the bit of content I want to quote so if I look in the content full itself you'll be able to see that I've got that environment ID now in here all I need to do is go to the content tab click on any bit of contents and as you'll see when we click on that content again in the URL you'll get access to the entry ID the other way of accessing this same ID is by the info tab right here clicking on it you can see that we've got the entry ID and then from here it's very easy to copy and paste it add it into post now aside from constructing a successful URL the other thing you'll need is the access token so the way that I like to do it in Postman is go to the authorization tab click in here set this type to oauth 2.0 with your token set it to available tokens Bearer and then put in your access token now remember this can either be your master access token or the preview access token depending on what type of content you want to query then after that simple case of doing a send you can see that we've now got a status of 200 and I've got all my data returned now when it comes to the data returned a typical response from content form will be broken into the sys type and this is basically metadata about the request Fields will be the property about the content item that you want to query three and then metadata this kind of like mess and then you also might get things like pagination in here now that we've mastered the API the SDK is really simple so let's look at the JavaScript one because it makes life easier in order to install the contentful connector just go to npm do npm install content now after you do this you can then establish connection so I'm not going to go through the complete code here I'll do that in a future video but what we can see is that we can import from contentful we do this create client and then from here we pass in the space we pass in that exact same access token and then from here as well we can also add in the environment Now by default the SDK is going to map to the master environment so you don't need to provide it after you successfully create that code to establish connection with API then the functions provided by the SDK pretty much marry up to the endpoints in the API so in our example if we want to query the CMS for a specific item of content we can use the get entries function within the SDK so we can do a client get entries from here we can pass in additional parameters so in this example we're passing in a content type of blog post so this is going to turn us multiple items and then from here we can always access those items within the items collection so if you look in the Json you'll see that the data is returned in the items object also if we look in entries you'll see that we have some pagination results things like limit skip bootle all that good stuff foreign content by arrest is also possible to query content full data using graphql now I'm not going to Deep dive into the benefits of graphql over rest here however some of the factors it has going for it include performance graphql only Returns the exact data you need in the presentation layer reduced Network calls the coupling of data and database models do its query structure it allows you to combine data from different content models more easily it can solve the over and under effective problem now if you decide you want to work with graphql I have a handy tip for you which will make querying much easier and that is a Marketplace app so basically if we go to apps right here go to Marketplace then do a search for graphql you'll see we have this graphql playground and from here after you install it you give it an API key but what you'll see is that in your app list you'll then have access to the playground and then clicking on this playground will basically give you access to a graphql Explorer now from here you can then start doing your graphql queries and testing them directly within the CMS itself so you can see here let's do total bow off my command we've got history so it's going to recognize what I've done previously but using this is way easier to get the data that you need rather than having to do it in code and recompile everything so yeah if you want to use graphql highly recommend you install this Marketplace app the next thing I want to talk about is probably the biggest hidden gotcha that you might encounter and this is around linked asset when it comes to your content modeling it's possible to create content models that basically reference another content model so what we can have is a chain of One content item links to another one which links to another one and we have all this sub nesting now when you use the rest API SDK the level of nesting that gets returned in your query is a bit variable so if you use get entry and you search for a single item you won't get any linked entries at all now if you use the get entries endpoint even if you search for a single individual item you'll also get linked assets which are linked to one level nesting depth now by the API it's possible to change all of this however it's very possible and you're bump into this all the time is it will search for something and it won't have all the data that you expect and in these instances you might need to make another query or you might need to use another endpoint now it's because we have these differences I typically find that just using get entries all the time and using get entries even if I'm searching for a single item is a little bit easier because it means all my codes are going to work the same way all the data and all the Json I'm going to get returned works the same way and I find it much easier to have a cleaner code base foreign management API and the purpose of this API is to allow you to perform more administrative operations with contentful remotely now the operation supported by this API include Space Management environment management content type management content management app debt management Locale management and loads more now as you might have guessed from the name the management API supports both read and write operations now this is different compared to the content delivery API which is only read only so A good rule to keep in mind when implementing the CMS is to use content delivery API when you want to render stuff on a web page or an app and use the management API when you want to update or write content instead now translating this into more technical terms the management API supports get put delete and post operation now the management API also has its own npm package and you can install this package using the command npm install contentful Dash manage room now one of the big gotchas with this API is when you want to update content programmatically now the reason for that is you also need to supply the correct version you want to update as an HTTP header and without supplying this value you will bump into version area whenever you update now the reason for this header is simple to stop people from accidentally overriding content the good news is that the content management npm package will automatically have the correct version number as an HTTP header for you when you're writing code the bad news is that you need to still apply this manually when you're calling the rest API directly you can get the latest version ID for any bit of content by using the get entries endpoints then in the return Json you should see the revision when it comes to accessing the content management API you will be using the API base URL of api.contentable.com so this is different compared to the content delivery API which uses cdn.contentful.com now another thing that you need to know is that when you're using the content management API you cannot reuse the same authorization token that you used with the content delivery API so let's go back into the CMS if we go to settings now go back down here go to API Keys now one of the things that you'll probably not notice the first time you look at this is that when you load the screen actually loads on a default content delivery preview token Tab and turn there right of it here you can see that we also have this content management tokens if you want to use the content management delivery API you're going to have to generate a Persona give your token a name so like admin access whatever and then from here you'll get given an SDK access token key whatever you want to call it now this is the token that you need to use with the content management API do not get tricked into using this one here because you will just get some access issues so that is tip one next we'll quickly look at how to construct the query in Postman for the content management API so we call the base URL API dot contentful.com in here we're passing in spaces space ID environments environment name and then this endpoint we're calling the content types endpoint whenever you're constructing a queried Content full you'll always need to add in the authorization header so go to authorization add it as oauth 2 set 8 available Bearer token and then remember to use the API token that allows for admin access after this in your HTTP headers don't forget you'll need to add in the x dash content for dash version for certain queries then if you actually want to query the content types endpoints you will need to add in the content type that you actually want to query within the quest body after doing all this if everything goes okay you should get a status okay and you'll get Jason returned from the response job is a good the final API that we're going to cover is the user management API now at first glance this API looks and behaves very similar to the content management API you can access both of these apis from the same at base URL which is api.contentable.com the user management API exposes endpoints to allow you to work with things like organization memberships invitations teams team memberships speech memberships space members space roles and users now I'm not going to cover all the API in detail but in essence if you want to remotely manage content editors this is the API to check out so as I'm hoping that you can see accessing contentful is pretty easy you have a number of ways however as long as you understand the fundamentals everything's pretty sweet and easy now we have reached that point in the video where if you haven't already don't forget to click on subscribe button so you catch up with this content and if you have found value in this video then please click on like because it helps you grow this channel now if you do want to learn more about contentful then the good news is that I've recorded other videos all about it so on the screen right now you should see a video all about how to set up contentful with next.js and necklace so if that sounds good to you click on that learn a little bit more otherwise I hope you're having a fantastic day wherever you are in this world and until next Sunday happy coding

Channel: jondjones

Views: 4,822

Keywords:

Id: LmKK_2AKmm8

Length: 17min 51sec (1071 seconds)

Published: Sun Mar 12 2023